@camstack/addon-provider-reolink 1.2.148 → 1.2.149

package/dist/addon.mjs

@@ -5385,7 +5385,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#endregion
-//#region ../types/dist/sleep-CaB_hL5g.mjs
+//#region ../types/dist/sleep-BVhJDJka.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -6956,6 +6956,18 @@ function systemMethod(input, output, options) {
 		systemOnly: true
 	};
 }
+/**
+* A method a SOURCE of a collection cap may legitimately not serve — OPTIONAL
+* on `InferProvider`. The `providerOptional: true` literal is what
+* `InferProvider` keys on; see {@link CapabilityMethodSchema.providerOptional}
+* for when this is the honest answer and when it is a soft stub.
+*/
+function optionalMethod(input, output, options) {
+	return {
+		...method(input, output, options),
+		providerOptional: true
+	};
+}
 /** Shorthand to define an event schema */
 function event(data) {
 	return { data };
@@ -25341,6 +25353,77 @@ var ClipPlaybackSchema = object({
 * which days it asked for and got nothing — "no clips" would be a lie about a
 * card that is full of them.
 */
+/**
+* The operator's authorisation to WAKE a sleeping camera for one clip read.
+*
+* ONE value, absent by default, and it is a `force`-shaped operator signal in
+* exactly the sense `snapshot-wake-gate.ts` uses the word: *"`snapshot.getSnapshot`'s
+* `force` flag, and nothing else… a background caller must never set it…
+* Stale but honest beats woken"*. A scheduler, a retry, a reconcile and a
+* prefetch never set it; a surface sets it only behind the same confirm the
+* "Wake and refresh" gesture uses, and it is refused below 15 % battery
+* exactly as that gesture is.
+*
+* The gate is decided BEFORE `getApi()`, because on UDP the login IS the wake
+* (D549) — a read that opened a session and then checked would have woken the
+* camera to find out it was not allowed to.
+*
+* **One authorised yes is one wake.** `next-natural` — take the clip the next
+* time the camera is awake for its own reasons — is deliberately not a member:
+* it was proposed, it is free on the battery, and the operator declined it on
+* 2026-09-20 (*"Quando un export viene richiesto si sveglia la camera."*,
+* D558 "Considered and not taken").
+*/
+var ClipWakeSchema = _enum(["authorised"]);
+/**
+* Hard ceiling on ONE {@link videoclipsCapability.methods.readClipBytes} — the
+* same 50 MiB `RECORDING_EXPORT_MAX_READ_BYTES` uses, and for the same second
+* reason: the envelope is unary, so a base64 payload is held whole (~1.33× its
+* size) in the provider AND in the caller, on a hub this repo has already
+* OOM'd once (D9/D18).
+*
+* Measured clips sit far below it — 92 KB–2.29 MB for a sub twin, 455 KB for a
+* 16 s main clip — so the bound bites rarely. "Rarely" is not "never": a long
+* 4K main twin can exceed it, and above the bound the provider REFUSES with
+* 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.
+*/
+var VIDEOCLIPS_MAX_READ_BYTES = 50 * 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,
+* and `served` says which twin the caller actually got.
+*/
+var ClipBytesSchema = object({
+	base64: string(),
+	contentType: string(),
+	/** Suggested filename, extension included. */
+	name: string(),
+	bytes: number().int().nonnegative(),
+	/**
+	* Which twin was actually served — the same contract
+	* {@link ClipPlaybackSchema.served} carries, and REQUIRED here because the
+	* export record persists it: a row read a week later must say the same thing
+	* the panel said at the moment of the tap. A missing main twin is never
+	* served silently as if it were the asked-for quality (D549 15).
+	*/
+	served: CamProfileSchema,
+	/**
+	* The DECODED duration of the delivered file, when the fetch measured one.
+	*
+	* A clip fetch verifies its own completion against the catalog row and
+	* retries a materially short pass (D568); this is that measurement, carried
+	* so a consumer can say the same thing rather than re-deriving it. Absent
+	* when the producer did not measure — never zero, which would say the file
+	* is empty.
+	*/
+	durationMs: number().positive().optional()
+});
 var ClipSourceAvailabilitySchema = object({
 	state: _enum([
 		"ok",
@@ -25512,6 +25595,68 @@ var videoclipsCapability = {
 		}), ClipPlaybackSchema, {
 			kind: "query",
 			auth: "protected"
+		}),
+		/**
+		* This clip's BYTES, base64, bounded — the by-handle read a clip EXPORT
+		* pulls once (D558).
+		*
+		* `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.
+		*
+		* Routing needs no `provider` pin: the id is source-prefixed and
+		* self-contained, so `device-collection-dispatch.ts` rule 3 hands the call
+		* to the source that claims it — and an id nobody claims is REFUSED rather
+		* than answered by another source.
+		*
+		* The producer reuses the fetch path it already has, completion rules
+		* included: a clip is taken by cmd 5 and finished on a short idle window
+		* whose result is PROVED against the catalog row's own span, retried once
+		* when it comes up materially short, and served-and-named when it is still
+		* short (D568). A second fetch with different completion rules is exactly
+		* the second authority D558 refuses to create.
+		*
+		* Every refusal THROWS with its reason and none of them is silent — the
+		* sleep gate (decided before `getApi()`, liftable only by
+		* {@link ClipWakeSchema}), a catalog row nobody claims, a clip with no
+		* bytes behind it, a mux that failed, and the size bound. The caller turns
+		* that reason into an operator-facing one; a truncated file is never an
+		* answer.
+		*/
+		readClipBytes: optionalMethod(object({
+			deviceId: number(),
+			clipId: string().min(1),
+			/**
+			* Which twin to fetch, on the mapping D549 15 already fixed:
+			* `low | mid` → the sub file, `high` → the main twin. `auto` is not
+			* accepted here for the same reason it is not accepted by
+			* `getClipPlayback` — a stored file has no broker session, so the
+			* adaptive tier cannot be resolved for it.
+			*/
+			profile: CamProfileSchema.optional(),
+			/**
+			* The CALLER's byte bound, so an over-size clip is refused before it is
+			* read and encoded rather than after. Capped by
+			* {@link VIDEOCLIPS_MAX_READ_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()
+		}), ClipBytesSchema, {
+			kind: "query",
+			auth: "protected"
 		})
 	}
 };
@@ -33465,13 +33610,101 @@ var ExportStateSchema = _enum([
 	"expired",
 	"deleted"
 ]);
-/** One export job / history row. */
+/**
+* WHAT an export is — the authority, as opposed to the four top-level fields
+* the Library sorts and labels on (D558 § 2.2).
+*
+* Read it through {@link exportSubjectOf}, never off the record directly: the
+* field is optional for the history rows written before it existed, and that
+* absence has exactly one interpreter.
+*/
+var ExportSubjectSchema = discriminatedUnion("kind", [object({
+	kind: literal("footage"),
+	deviceId: number(),
+	profiles: array(string()).min(1),
+	fromMs: number(),
+	toMs: number()
+}), object({
+	kind: literal("clip"),
+	deviceId: number(),
+	provider: string().min(1),
+	source: string().min(1),
+	sourceLabel: string().min(1),
+	clipId: string().min(1),
+	/**
+	* WHERE IN THE CATALOG to confirm this clip — the day window the surface was
+	* already listing when the operator picked the segment.
+	*
+	* It is **not** a time range control and it never becomes one: the record's
+	* `fromMs`/`toMs` come from the catalog ROW and from nothing a caller
+	* supplied (D558 § 5.4.3), and a window that does not contain the clip is a
+	* `catalog-miss`, not a silently wider search. It exists because
+	* `videoclips.listClips` takes `since`/`until` and has no by-handle twin:
+	* the catalog check D558 asks for is literally that call, and a call needs a
+	* window. The surface has one — `ClipsBrowser`'s `dayWindow`, one local
+	* wall-clock day, which is also the only width measured to be cheap (one
+	* day on 592 lists 171 clips in 712 ms, a busy day 546 in 2.0 s; twenty days
+	* of one child's events took 3.6–5.4 s).
+	*/
+	catalogWindow: object({
+		sinceMs: number(),
+		untilMs: number()
+	}),
+	profile: _enum([
+		"high",
+		"mid",
+		"low"
+	]),
+	/**
+	* The operator's authorisation to wake a sleeping camera for this export.
+	* ONE definition, in the cap that owns the clip read ({@link ClipWakeSchema}),
+	* because the gate that honours it is the clip provider's sleep gate — a
+	* second enum here would be a second contract. Absent by default; never
+	* settable by a scheduler or a retry.
+	*
+	* **One authorised yes is ONE wake.** A failed clip export is retried only by
+	* an operator act that asks again; a queued job that outlived its wake fails
+	* with a reason rather than waking on its turn; and this subject carries
+	* exactly one profile precisely so one tap is never two fetches (D558 § 5.2).
+	*/
+	wake: ClipWakeSchema.optional()
+})]);
+/**
+* One export job / history row.
+*
+* **`subject` is the AUTHORITY on what was exported. `deviceId`, `profile`,
+* `fromMs` and `toMs` are its PROJECTION** — kept top-level because the whole
+* Library sorts and labels on them (`library-items.ts` orders an export by
+* `fromMs`; `export-format.ts` draws `rangeLabel` from the pair), and a row
+* that did not fill them would sort under the epoch and render a blank range.
+* Write to the subject and read from the projection and the two will disagree;
+* the projection is derived at creation and never edited afterwards.
+*
+* And they mean DIFFERENT FACTS for the two kinds, which is the part a reader
+* who knows only the recording export will get wrong:
+*
+* | field | `kind:'footage'` | `kind:'clip'` |
+* | --- | --- | --- |
+* | `fromMs`/`toMs` | the stretch the operator ASKED for | the camera's own boundaries, always `clip.timeRange`, never anything a caller supplied |
+* | `profile` | the stream rendered | the twin actually SERVED (`subject.profile` is the one asked for) |
+*
+* Same type, different fact — the shape this repo keeps getting wrong (D385's
+* two authorities, D224's second copy).
+*/
 var ExportRecordSchema = object({
 	id: string(),
 	deviceId: number(),
 	profile: string(),
 	fromMs: number(),
 	toMs: number(),
+	/**
+	* What this export IS. Optional ONLY for the rows written before D558: the
+	* store parses every row through this schema on every read, so a required
+	* field would make the export AUDIT — which is the whole reason rows survive
+	* file deletion — unreadable in one release. Absence means `footage`, and
+	* {@link exportSubjectOf} is the one place that says so.
+	*/
+	subject: ExportSubjectSchema.optional(),
 	options: ExportOptionsSchema,
 	state: ExportStateSchema,
 	/** 0–100 while rendering; null otherwise. */
@@ -33488,6 +33721,22 @@ var ExportRecordSchema = object({
 	/** Failure reason when state is 'failed'; null otherwise. */
 	error: string().nullable()
 });
+_enum([
+	"catalog-miss",
+	"catalog-unreachable",
+	"no-file-for-window",
+	"clip-in-progress",
+	"unsupported-option",
+	"sleeping",
+	"camera-refused",
+	"fetch-failed",
+	"too-large-to-transfer",
+	"wake-expired"
+]);
+/** `<token>: <prose>` — the ONE composition of a clip export's failure string. */
+function clipExportFailure(code, detail) {
+	return detail.length > 0 ? `${code}: ${detail}` : code;
+}
 /** Candidate download URLs (LAN first, then operator extra hosts). */
 var ExportDownloadSchema = object({
 	url: string(),
@@ -33506,16 +33755,50 @@ var ExportBytesSchema = object({
 	name: string(),
 	bytes: number().int().nonnegative()
 });
+/** Canonical `profiles[]`, falling back to the legacy singular `profile`. */
+function resolveExportProfiles(input) {
+	if (input.profiles !== void 0 && input.profiles.length > 0) return [...input.profiles];
+	if (typeof input.profile === "string" && input.profile.length > 0) return [input.profile];
+	return [];
+}
 method(object({
 	deviceId: number(),
 	/** @deprecated Prefer `profiles`. Kept so timelapse/notifiers keep working. */
 	profile: string().optional(),
 	profiles: array(string()).min(1).optional(),
-	fromMs: number(),
-	toMs: number(),
+	/** Footage only — a clip's boundaries are the camera's. */
+	fromMs: number().optional(),
+	toMs: number().optional(),
+	/** What to export. Absent means the legacy flat footage request. */
+	subject: ExportSubjectSchema.optional(),
 	options: ExportOptionsSchema
 }).superRefine((v, ctx) => {
-	if ((v.profiles !== void 0 && v.profiles.length > 0 ? v.profiles : v.profile !== void 0 ? [v.profile] : []).length < 1) ctx.addIssue({
+	if (v.subject?.kind === "clip") {
+		if (v.subject.deviceId !== v.deviceId) ctx.addIssue({
+			code: ZodIssueCode.custom,
+			message: `subject.deviceId (${v.subject.deviceId}) must equal deviceId (${v.deviceId}) — the top-level field is what per-device scope enforcement reads`,
+			path: ["subject", "deviceId"]
+		});
+		if (v.fromMs !== void 0 || v.toMs !== void 0) ctx.addIssue({
+			code: ZodIssueCode.custom,
+			message: "a clip export asks for no time range: the camera chose the boundaries and they are read from the catalog row",
+			path: ["fromMs"]
+		});
+		return;
+	}
+	if (v.subject?.kind === "footage" && v.subject.deviceId !== v.deviceId) ctx.addIssue({
+		code: ZodIssueCode.custom,
+		message: `subject.deviceId (${v.subject.deviceId}) must equal deviceId (${v.deviceId})`,
+		path: ["subject", "deviceId"]
+	});
+	const fromMs = v.subject?.kind === "footage" ? v.subject.fromMs : v.fromMs;
+	const toMs = v.subject?.kind === "footage" ? v.subject.toMs : v.toMs;
+	if (typeof fromMs !== "number" || typeof toMs !== "number") ctx.addIssue({
+		code: ZodIssueCode.custom,
+		message: "a footage export needs fromMs and toMs",
+		path: ["fromMs"]
+	});
+	if ((v.subject?.kind === "footage" ? [...v.subject.profiles] : resolveExportProfiles(v)).length < 1) ctx.addIssue({
 		code: ZodIssueCode.custom,
 		message: "pass profiles[] (min 1) or legacy profile",
 		path: ["profiles"]
@@ -44057,6 +44340,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"videoclips.readClipBytes": {
+		capName: "videoclips",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"viewerUi.getStaticDir": {
 		capName: "viewer-ui",
 		capScope: "system",
@@ -46075,6 +46364,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"videoclips.readClipBytes": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"waterHeater.setAway": [{
 		name: "deviceId",
 		form: "single",
@@ -148434,6 +148728,43 @@ var ClipThumbQueue = class {
 	}
 };
 //#endregion
+//#region src/clips/clip-prefetch.ts
+/** The longest a device may stay quiet after refusals, whatever its interval. */
+var PREFETCH_QUIET_MAX_MS = 720 * 6e4;
+/**
+* How long a device that refused stays un-asked, in INTERVALS rather than
+* wall-clock: the refresh interval is an operator setting (5 min – 24 h), and
+* a quiet period in minutes would be either no gap at all at one end or a day
+* at the other. One refusal skips the next two passes, two skips four, and so
+* on, capped.
+*/
+function prefetchQuietMs(consecutiveRefusals, intervalMs) {
+	if (consecutiveRefusals <= 0) return 0;
+	const doubled = intervalMs * 2 ** consecutiveRefusals;
+	return Number.isFinite(doubled) ? Math.min(doubled, PREFETCH_QUIET_MAX_MS) : PREFETCH_QUIET_MAX_MS;
+}
+/**
+* May this camera's stills be prefetched right now?
+*
+* The topology comes first and is absolute: no amount of idle host or empty
+* ladder makes a still on a standalone battery camera free.
+*/
+function decideClipPrefetch(input) {
+	if (input.mode === "forced-wake") return {
+		kind: "skip",
+		reason: "battery-wake-cost"
+	};
+	if (input.quiet) return {
+		kind: "skip",
+		reason: "quiet-after-refusal"
+	};
+	if (input.hostBusy) return {
+		kind: "skip",
+		reason: "host-busy"
+	};
+	return { kind: "run" };
+}
+//#endregion
 //#region src/clips/clip-identity.ts
 /**
 * A Reolink clip's IDENTITY — the id the operator's surface carries around and
@@ -149025,6 +149356,18 @@ function normaliseHour(hour) {
 }
 //#endregion
 //#region src/clips/reolink-videoclips-provider.ts
+/**
+* The filename an export carries away, from the camera's own handle.
+*
+* A hub child's handle is a full path (`/mnt/sda/U10…/RecS02_….mp4`) and a
+* standalone's is a bare name, so only the last segment is a name; the
+* extension is re-stated because what we produce is an MP4 whatever the
+* camera called its file.
+*/
+function clipFileLabel(fileName) {
+	const stem = (fileName.split("/").at(-1) ?? fileName).replace(/\.[^.]+$/, "");
+	return `${stem === "" ? "clip" : stem}.mp4`;
+}
 function createReolinkVideoclipsProvider(deps) {
 	/** Last known availability per `deviceId|source`, written by every read. */
 	const health = /* @__PURE__ */ new Map();
@@ -149345,6 +149688,120 @@ function createReolinkVideoclipsProvider(deps) {
 				format: "mp4",
 				served: prepared.served
 			};
+		},
+		/**
+		* This clip's BYTES, base64, bounded — the producing half of a clip
+		* export (D558 § 3, D572).
+		*
+		* ## What it refuses, and in whose words
+		*
+		* Every exit throws `clipExportFailure(<token>, <prose>)`. The engine
+		* recovers the token with `clipExportFailureOf` and BELIEVES it; anything
+		* that does not parse becomes `fetch-failed` with the prose kept verbatim.
+		* So a refusal this side can name is named here — a `sleeping` that
+		* arrives as prose is a `sleeping` the modal cannot render.
+		*
+		* ## The order of the questions, and why it is this order
+		*
+		* The cheap ones come first and none of them touches the camera: the id,
+		* the row, whether the file is still being written, which twin exists, and
+		* the SIZE the catalog already declared for it. A main twin over the bound
+		* is refused for nothing — no session, no transfer, no mux — which is the
+		* rule bulk work over stored media already follows (D54). Only then does
+		* `prepareBytes` reach a camera, behind the sleep gate that has to sit in
+		* front of the login.
+		*
+		* ## `high` against a 50 MiB ceiling
+		*
+		* A missing main twin is a DIVERGENCE, not a refusal: the sub is served
+		* and `served` says `low`, exactly as the player does (D549 15), because
+		* 17 of 546 clips on 592 have no main copy and an export of the copy that
+		* exists beats no export. A main twin that exists and is too BIG is the
+		* other case and is refused by name — the cap's own docblock settles it
+		* ("above the bound the provider REFUSES with the size in the message,
+		* never truncates"), the operator keeps the unbounded playback route for
+		* that file, and the chunked read the cap names is what removes the
+		* refusal rather than a silent 33× quality substitution.
+		*/
+		readClipBytes: async ({ deviceId, clipId, profile, maxBytes, wake }) => {
+			const tags = { deviceId };
+			const refuse = (code, detail, meta) => {
+				deps.logger.warn("videoclips: refusing a clip byte read", {
+					tags,
+					meta: {
+						clipId,
+						branch: code,
+						...meta
+					}
+				});
+				throw new Error(clipExportFailure(code, detail));
+			};
+			const parsed = parseClipId(clipId);
+			if (parsed === null) return refuse("catalog-miss", `clip id "${clipId}" was not minted by the Reolink provider`, {});
+			const clipKey = clipKeyFor(parsed.channel, parsed.fileName);
+			const row = rowsByKey.get(`${deviceId}|${clipKey}`);
+			if (row === void 0) return refuse("catalog-miss", `clip "${clipId}" is not in this node's catalog for device ${deviceId} — list the day that holds it first`, { clipKey });
+			if (row.inProgress === true) return refuse("clip-in-progress", `clip "${clipId}" is still being written, so it has no end to export`, { clipKey });
+			const mainFileName = profile === "high" ? row.mainFileName : void 0;
+			if (profile === "high" && mainFileName === void 0) deps.logger.warn("videoclips: no main twin for this clip — serving the sub copy", {
+				tags,
+				meta: {
+					clipId,
+					clipKey,
+					branch: "no-main-twin",
+					asked: profile
+				}
+			});
+			const twin = mainFileName === void 0 ? "sub" : "main";
+			const fileName = mainFileName ?? row.subFileName;
+			if (fileName === "") return refuse("no-file-for-window", `clip "${clipId}" is listed with no byte handle behind it`, {
+				clipKey,
+				twin
+			});
+			const served = twin === "main" ? "high" : "low";
+			const bound = Math.min(maxBytes ?? 52428800, VIDEOCLIPS_MAX_READ_BYTES);
+			const declaredBytes = twin === "main" ? row.mainBytes : row.subBytes;
+			if (declaredBytes !== void 0 && declaredBytes > bound) return refuse("too-large-to-transfer", `the camera lists the ${twin} file of clip "${clipId}" as ${declaredBytes} bytes, over the ${bound}-byte bound for an inline read — play it from its playback URL instead`, {
+				clipKey,
+				twin,
+				declaredBytes,
+				bound
+			});
+			const outcome = await deps.prepareBytes({
+				deviceId,
+				row,
+				fileName,
+				twin,
+				...wake !== void 0 ? { wake } : {}
+			});
+			if (outcome.kind === "refused") throw new Error(clipExportFailure(outcome.code, outcome.detail));
+			if (outcome.bytes.byteLength > bound) return refuse("too-large-to-transfer", `clip "${clipId}" muxed to ${outcome.bytes.byteLength} bytes, over the ${bound}-byte bound for an inline read`, {
+				clipKey,
+				twin,
+				bytes: outcome.bytes.byteLength,
+				bound
+			});
+			deps.logger.info("videoclips: served a Reolink clip inline", {
+				tags,
+				meta: {
+					clipId,
+					clipKey,
+					twin,
+					served,
+					asked: profile ?? null,
+					bytes: outcome.bytes.byteLength,
+					durationMs: outcome.durationMs,
+					wake: wake ?? "none"
+				}
+			});
+			return {
+				base64: outcome.bytes.toString("base64"),
+				contentType: "video/mp4",
+				name: clipFileLabel(fileName),
+				bytes: outcome.bytes.byteLength,
+				served,
+				...outcome.durationMs !== null ? { durationMs: outcome.durationMs } : {}
+			};
 		}
 	};
 	/**
@@ -149606,6 +150063,12 @@ var ClipCatalogRefreshScheduler = class {
 	lastRunAt = /* @__PURE__ */ new Map();
 	/** Cameras whose refresh has not come back yet. */
 	inFlight = /* @__PURE__ */ new Set();
+	/** Consecutive prefetch passes this camera stopped on a refusal. Cleared by
+	*  the first pass that lands, so a camera that recovers is asked again on
+	*  the very next tick. */
+	prefetchRefusals = /* @__PURE__ */ new Map();
+	/** Until when this camera's prefetch stays un-asked. */
+	prefetchQuietUntil = /* @__PURE__ */ new Map();
 	constructor(deps) {
 		this.deps = deps;
 	}
@@ -149675,6 +150138,7 @@ var ClipCatalogRefreshScheduler = class {
 					elapsedMs: this.deps.now() - now
 				}
 			});
+			await this.prefetch(target, mode);
 		} catch (err) {
 			this.deps.markStale(target.deviceId);
 			this.deps.logger.warn("videoclips: catalog refresh failed — the catalog stays as it was", {
@@ -149689,10 +150153,92 @@ var ClipCatalogRefreshScheduler = class {
 			this.inFlight.delete(target.deviceId);
 		}
 	}
+	/**
+	* The still prefetch for a camera whose catalog was just re-read.
+	*
+	* It NEVER throws — a prefetch is an enhancement to a refresh that already
+	* landed, and letting it reach the refresh's own catch would mark a catalog
+	* stale that is not. Every exit says which branch it took, per camera.
+	*/
+	async prefetch(target, mode) {
+		const deviceId = target.deviceId;
+		const tags = { deviceId };
+		const quietUntil = this.prefetchQuietUntil.get(deviceId) ?? 0;
+		const decision = decideClipPrefetch({
+			mode,
+			hostBusy: this.deps.hostBusy(target.hostKey),
+			quiet: quietUntil > this.deps.now()
+		});
+		if (decision.kind === "skip") {
+			this.deps.logger.info("videoclips: still prefetch skipped", {
+				tags,
+				meta: {
+					branch: `prefetch-${decision.reason}`,
+					mode,
+					host: target.hostKey,
+					quietForMs: Math.max(0, quietUntil - this.deps.now())
+				}
+			});
+			return;
+		}
+		try {
+			const outcome = await this.deps.prefetchStills(deviceId);
+			if (outcome.stop === "refused") {
+				this.quieten(target, {
+					branch: "prefetch-refused",
+					mode,
+					minted: outcome.minted,
+					scanned: outcome.scanned,
+					alreadyHeld: outcome.alreadyHeld,
+					code: outcome.refusal?.code ?? null,
+					disposition: outcome.refusal?.disposition ?? null,
+					clipKey: outcome.refusal?.clipKey ?? null
+				});
+				return;
+			}
+			this.prefetchRefusals.delete(deviceId);
+			this.prefetchQuietUntil.delete(deviceId);
+			this.deps.logger.info("videoclips: stills prefetched", {
+				tags,
+				meta: {
+					branch: `prefetch-${outcome.stop}`,
+					mode,
+					minted: outcome.minted,
+					scanned: outcome.scanned,
+					alreadyHeld: outcome.alreadyHeld
+				}
+			});
+		} catch (err) {
+			this.quieten(target, {
+				branch: "prefetch-failed",
+				mode,
+				error: errMessage$1(err)
+			});
+		}
+	}
+	/** Arm the doubling quiet period and say so, with what the pass reported. */
+	quieten(target, meta) {
+		const deviceId = target.deviceId;
+		const refusals = (this.prefetchRefusals.get(deviceId) ?? 0) + 1;
+		this.prefetchRefusals.set(deviceId, refusals);
+		const quietForMs = prefetchQuietMs(refusals, target.intervalMinutes * 6e4);
+		this.prefetchQuietUntil.set(deviceId, this.deps.now() + quietForMs);
+		this.deps.logger.warn("videoclips: still prefetch stopped — the host is not serving stills", {
+			tags: { deviceId },
+			meta: {
+				...meta,
+				host: target.hostKey,
+				consecutiveRefusals: refusals,
+				quietForMs
+			}
+		});
+	}
 };
 function errMessage$1(err) {
 	return err instanceof Error ? err.message : String(err);
 }
+//#endregion
+//#region src/clips/clip-service.ts
 function createClipService(deps) {
 	const now = deps.now ?? (() => Date.now());
 	const cache = new ClipCatalogCache({ now });
@@ -149715,8 +150261,15 @@ function createClipService(deps) {
 		ffmpegBinaryPath: deps.ffmpegBinaryPath ?? "ffmpeg",
 		spawnFn: spawn$1
 	});
-	/** One prepare per clip: two clicks on one row must not pay cmd 5 twice. */
-	const preparing = /* @__PURE__ */ new Map();
+	/**
+	* One production per `(device, clip, twin)`: two clicks on one row — or a
+	* click and an EXPORT of the same row — must not pay cmd 5 twice. It is
+	* keyed by the twin because the two files are different bytes, and it is
+	* shared by the player and the byte read because those two are the only
+	* callers there are: an in-flight map per caller would be a second wake on
+	* a battery camera the operator authorised once.
+	*/
+	const producing = /* @__PURE__ */ new Map();
 	const rowFor = (deviceId, clipKey) => {
 		return cache.findBy(deviceId, (row) => row.clipKey === clipKey);
 	};
@@ -149783,14 +150336,14 @@ function createClipService(deps) {
 	* transfer, and that window is short. What makes it safe is not the window,
 	* it is the decoded duration judged against the row that asked for it.
 	*/
-	const fetchVerifiedClipBytes = async (device, row, clipKey) => {
+	const fetchVerifiedClipBytes = async (device, row, clipKey, fileName) => {
 		const deviceId = device.deviceId;
 		const api = await device.getApi();
 		const fetchPass = (idleTimeoutMs) => fetchClipBytes({
 			download: () => api.downloadRecordingDemuxed({
 				channel: device.channel,
 				...device.uid !== void 0 ? { uid: device.uid } : {},
-				fileName: row.subFileName,
+				fileName,
 				idleTimeoutMs
 			}),
 			sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
@@ -149865,43 +150418,100 @@ function createClipService(deps) {
 		});
 		return kept;
 	};
-	const prepareClip = async (deviceId, clipKey) => {
-		const ready = await media.pathIfPresent(deviceId, clipKey);
-		if (ready !== null) return ready;
-		const key = `${deviceId}|${clipKey}`;
-		const inFlight = preparing.get(key);
-		if (inFlight !== void 0) return inFlight;
-		const run = prepareClipOnce(deviceId, clipKey).finally(() => {
-			preparing.delete(key);
-		});
-		preparing.set(key, run);
-		return run;
-	};
-	const prepareClipOnce = async (deviceId, clipKey) => {
+	/**
+	* ONE production of one twin's MP4 — the only place a clip's bytes are made.
+	*
+	* The player and `readClipBytes` are both served from here, which is the
+	* whole point: D568's completion rules (the 300 ms window, the decoded
+	* duration proved against the row, the single retry on 2 000 ms) and D567's
+	* mux (the MEASURED rate, the AAC copy, `+faststart`) exist once. A byte
+	* read with its own fetch would be the second authority those records were
+	* written to prevent.
+	*
+	* It never throws for a gated branch: every exit is a NAMED refusal in the
+	* clip-export vocabulary, so the provider can hand the engine a token it
+	* believes rather than prose it has to guess at (D572).
+	*/
+	const produceTwin = async (input) => {
+		const { deviceId, row, fileName, twin } = input;
+		const clipKey = row.clipKey;
+		const tags = { deviceId };
 		const device = await deps.resolveDevice(deviceId);
-		if (device === null) return null;
+		if (device === null) {
+			deps.logger.warn("videoclips: no Reolink camera here to fetch this clip from", {
+				tags,
+				meta: {
+					clipKey,
+					twin,
+					branch: "unknown-device"
+				}
+			});
+			return {
+				kind: "refused",
+				code: "catalog-unreachable",
+				detail: `device ${deviceId} is not a Reolink camera on this node`
+			};
+		}
 		if (device.isBattery && device.sleeping && !device.isHubChild) {
-			deps.logger.warn("videoclips: refusing to fetch a clip from a sleeping camera", {
-				tags: { deviceId },
+			if (input.wake !== "authorised") {
+				deps.logger.warn("videoclips: refusing to fetch a clip from a sleeping camera", {
+					tags,
+					meta: {
+						clipKey,
+						twin,
+						branch: "sleeping"
+					}
+				});
+				return {
+					kind: "refused",
+					code: "sleeping",
+					detail: `device ${deviceId} is a standalone battery camera and is sleeping — fetching a clip would wake it, and no operator authorisation was carried`
+				};
+			}
+			deps.logger.warn("videoclips: waking a sleeping battery camera on an authorised clip read", {
+				tags,
 				meta: {
 					clipKey,
-					branch: "sleeping"
+					twin,
+					branch: "wake-authorised"
 				}
 			});
-			return null;
 		}
-		const row = rowFor(deviceId, clipKey);
-		if (row === null) {
-			deps.logger.warn("videoclips: no catalog row for this clip", {
-				tags: { deviceId },
+		if (uidIsMissing(device)) {
+			deps.logger.warn("videoclips: no uid for this camera — its clip cannot be addressed", {
+				tags,
 				meta: {
 					clipKey,
-					branch: "no-catalog-row"
+					twin,
+					branch: "uid-missing"
 				}
 			});
-			return null;
+			return {
+				kind: "refused",
+				code: "catalog-unreachable",
+				detail: UID_MISSING_REASON
+			};
+		}
+		let downloaded;
+		try {
+			downloaded = await fetchVerifiedClipBytes(device, row, clipKey, fileName);
+		} catch (err) {
+			const reason = err instanceof Error ? err.message : String(err);
+			deps.logger.warn("videoclips: the camera never delivered this clip", {
+				tags,
+				meta: {
+					clipKey,
+					twin,
+					branch: "camera-refused",
+					error: reason
+				}
+			});
+			return {
+				kind: "refused",
+				code: "camera-refused",
+				detail: reason
+			};
 		}
-		const downloaded = await fetchVerifiedClipBytes(device, row, clipKey);
 		const audio = decideClipAudio(downloaded.audio);
 		if (audio.kind === "silent") deps.logger.warn("videoclips: serving a clip with no sound", {
 			tags: { deviceId },
@@ -149945,14 +150555,24 @@ function createClipService(deps) {
 					tags: { deviceId },
 					meta: {
 						clipKey,
+						twin,
 						branch: "mux-failed",
 						error: failure
 					}
 				});
-				return null;
+				return {
+					kind: "refused",
+					code: "fetch-failed",
+					detail: failure
+				};
 			}
 			const muxed = await readFile(outPath);
-			return await media.put(deviceId, clipKey, muxed);
+			const decoded = downloaded.stats.durationSeconds;
+			return {
+				kind: "ok",
+				bytes: muxed,
+				durationMs: decoded !== null && Number.isFinite(decoded) && decoded > 0 ? Math.round(decoded * 1e3) : null
+			};
 		} finally {
 			await rm(scratch, {
 				recursive: true,
@@ -149960,6 +150580,85 @@ function createClipService(deps) {
 			});
 		}
 	};
+	/** {@link produceTwin}, deduplicated per `(device, clip, twin)`. */
+	const produceOnce = (input) => {
+		const key = `${input.deviceId}|${input.row.clipKey}|${input.twin}`;
+		const inFlight = producing.get(key);
+		if (inFlight !== void 0) return inFlight;
+		const run = produceTwin(input).finally(() => {
+			producing.delete(key);
+		});
+		producing.set(key, run);
+		return run;
+	};
+	/**
+	* The PLAYER's path: the sub twin, filed in the scratch, served by URL.
+	*
+	* `null` for every refusal — the playback route answers a status code and
+	* has no vocabulary to carry a token; the named reason is already in the log
+	* line `produceTwin` wrote.
+	*/
+	const prepareClip = async (deviceId, clipKey) => {
+		const ready = await media.pathIfPresent(deviceId, clipKey);
+		if (ready !== null) return ready;
+		const row = rowFor(deviceId, clipKey);
+		if (row === null) {
+			deps.logger.warn("videoclips: no catalog row for this clip", {
+				tags: { deviceId },
+				meta: {
+					clipKey,
+					branch: "no-catalog-row"
+				}
+			});
+			return null;
+		}
+		const outcome = await produceOnce({
+			deviceId,
+			row,
+			fileName: row.subFileName,
+			twin: "sub"
+		});
+		if (outcome.kind !== "ok") return null;
+		return media.put(deviceId, clipKey, outcome.bytes);
+	};
+	/**
+	* The EXPORT's path: the asked twin's bytes, in memory, once.
+	*
+	* The scratch is the PLAYER's cache and its key
+	* (`clipKeyFor(channel, subFileName)`) carries no twin, so it holds exactly
+	* one thing: the sub file. A `sub` read therefore reuses it and warms it — a
+	* clip the operator just watched costs no second cmd 5, and one he exports
+	* first is already there when he plays it. A `main` read BYPASSES it in both
+	* directions: writing a main file under that key would serve 33× the bytes
+	* to every `low` playback of the clip, and filing it under a second key
+	* would evict the sub clips the player really does re-read (10 files /
+	* 200 MiB per device) to cache a one-shot export nobody reads twice.
+	*/
+	const prepareBytes = async (input) => {
+		const { deviceId, row, twin } = input;
+		if (twin === "sub") {
+			const cached = await media.read(deviceId, row.clipKey);
+			if (cached !== null) {
+				deps.logger.info("videoclips: a clip byte read was served from the scratch", {
+					tags: { deviceId },
+					meta: {
+						clipKey: row.clipKey,
+						twin,
+						branch: "scratch-hit",
+						bytes: cached.byteLength
+					}
+				});
+				return {
+					kind: "ok",
+					bytes: cached,
+					durationMs: null
+				};
+			}
+		}
+		const outcome = await produceOnce(input);
+		if (outcome.kind === "ok" && twin === "sub") await media.put(deviceId, row.clipKey, outcome.bytes);
+		return outcome;
+	};
 	const provider = createReolinkVideoclipsProvider({
 		now,
 		cache,
@@ -149971,6 +150670,7 @@ function createClipService(deps) {
 			playbackUrl: `/addon/${REOLINK_ADDON_ID}/${CLIP_MEDIA_PREFIX}/${device.deviceId}/${clipKey}.mp4`,
 			served: profile === "high" ? "high" : "low"
 		}),
+		prepareBytes,
 		logger: deps.logger
 	});
 	return {
@@ -149997,15 +150697,36 @@ function createClipService(deps) {
 			resolvePath: (deviceId, clipKey, _req) => prepareClip(deviceId, clipKey),
 			logger: deps.logger
 		}),
-		prefetchThumbnails: async (deviceId, limit = 20) => {
-			const rows = cache.allRows(deviceId).toSorted((a, b) => b.startMs - a.startMs).slice(0, limit);
+		prefetchThumbnails: async (deviceId, limit = 60) => {
+			const rows = cache.allRows(deviceId).toSorted((a, b) => b.startMs - a.startMs);
 			let minted = 0;
+			let scanned = 0;
+			let alreadyHeld = 0;
+			const outcome = (stop, refusal = null) => ({
+				minted,
+				scanned,
+				alreadyHeld,
+				stop,
+				refusal
+			});
+			if (!await thumbs.hasHeadroomForPrefetch(deviceId)) return outcome("no-headroom");
 			for (const row of rows) {
-				if (!await thumbs.hasHeadroomForPrefetch(deviceId)) break;
-				if (await thumbs.has(deviceId, row.clipKey)) continue;
-				if ((await mintThumbnail(deviceId, row.clipKey, "prefetch")).ok) minted += 1;
+				scanned += 1;
+				if (await thumbs.has(deviceId, row.clipKey)) {
+					alreadyHeld += 1;
+					continue;
+				}
+				if (minted >= limit) return outcome("budget");
+				const result = await mintThumbnail(deviceId, row.clipKey, "prefetch");
+				if (!result.ok) return outcome("refused", {
+					code: result.code,
+					disposition: result.disposition,
+					clipKey: row.clipKey
+				});
+				minted += 1;
+				if (minted % 16 === 0 && !await thumbs.hasHeadroomForPrefetch(deviceId)) return outcome("no-headroom");
 			}
-			return minted;
+			return outcome("rows-exhausted");
 		}
 	};
 }
@@ -164144,6 +164865,7 @@ var ReolinkProviderAddon = class extends BaseDeviceProvider {
 				if (!(device instanceof ReolinkCamera)) throw new Error(`clip refresh: device ${String(deviceId)} is not a Reolink camera here`);
 				await device.wakeForClipCatalogRefresh();
 			},
+			prefetchStills: async (deviceId) => service.prefetchThumbnails(deviceId),
 			hostBusy: (hostKey) => service.hostBusy(hostKey),
 			logger: this.ctx.logger
 		});