@camstack/addon-export-hap 1.2.128 → 1.2.132

package/dist/hap-export.addon.mjs

@@ -3,9 +3,9 @@ import { spawn } from "node:child_process";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import * as path from "node:path";
 import { join } from "node:path";
-import { createWriteStream, readFileSync } from "node:fs";
+import { createReadStream, createWriteStream, readFileSync } from "node:fs";
 import * as fs from "node:fs/promises";
-import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { once } from "node:events";
 import { createSocket } from "node:dgram";
 import { networkInterfaces } from "node:os";
@@ -5399,7 +5399,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#endregion
-//#region ../types/dist/sleep-CiR4z7r9.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).
@@ -7029,6 +7029,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
+	};
+}
 var StaticDirOutputSchema$1 = object({ staticDir: string() });
 var VersionOutputSchema$1 = object({ version: string() });
 method(_void(), StaticDirOutputSchema$1, { auth: "admin" }), method(_void(), VersionOutputSchema$1, { auth: "admin" });
@@ -8052,6 +8064,8 @@ var EVENT_OWNER_TYPES = [
 * nothing failing until a caller asked.
 */
 var EventOwnerTypeSchema = _enum(EVENT_OWNER_TYPES);
+/** The same list as a Zod enum, for the cap input that carries it. */
+var MediaPresenceOwnerKindSchema = _enum([...EVENT_OWNER_TYPES, "track"]);
 new Set(EVENT_OWNER_TYPES);
 var EncodeProfileSchema = object({
 	video: object({
@@ -9665,20 +9679,86 @@ var StorageCleanupJobSchema = object({
 });
 var StorageCleanupStatusInputSchema = object({ jobId: string().optional() });
 /**
-* The one typed state of a storage location. Authoritative Zod schema — the TS
-* alias below is `z.infer<>` of it, never a second spelling.
+* The storage-location STATE MODEL (D385) — one typed state, one policy module.
+*
+* A location's state used to be split across two authorities: the typed
+* `enabled` field (THE write switch since D383) and an untyped `config.readOnly`
+* key. They did not mean the same thing — `enabled: false` was still evicted
+* under disk pressure while `config.readOnly` was deliberately excluded — and
+* neither name said which. Every consumer re-derived the difference, and the
+* three questions that actually matter were answered in six places.
+*
+* This module is the ONLY place in the repo allowed to interpret the state. It
+* answers three questions and nothing else:
+*
+*   - may this location be WRITTEN to?   {@link modeMayWrite}
+*   - may this location be READ?          {@link modeMayRead}
+*   - what is its eviction policy?        {@link evictionPolicyForMode}
+*
+* | mode       | write | read | eviction                       |
+* | ---------- | ----- | ---- | ------------------------------ |
+* | `active`   | yes   | yes  | `normal` (pressure + usage cap) |
+* | `readonly` | no    | yes  | `never`                        |
+* | `drain`    | no    | yes  | `drain` (paced, until empty)   |
+* | `disabled` | no    | no   | `never`                        |
+*
+* `scripts/check-storage-location-mode-single-owner.ts` fails the build when
+* anything outside this module reads `config['readOnly']` or compares `enabled`
+* directly. A rule nothing checks has already been broken somewhere.
 */
-var StorageLocationModeSchema = _enum([
+var STORAGE_LOCATION_MODES = [
 	"active",
 	"readonly",
 	"drain",
 	"disabled"
-]);
+];
+/**
+* The one typed state of a storage location. Authoritative Zod schema — the TS
+* alias below is `z.infer<>` of it, never a second spelling.
+*/
+var StorageLocationModeSchema = _enum(STORAGE_LOCATION_MODES);
 _enum([
 	"normal",
 	"never",
 	"drain"
 ]);
+/** Is this mode a write target? Only `active` is. */
+function modeMayWrite(mode) {
+	return mode === "active";
+}
+/**
+* The mode a LEGACY row implies, or `null` when it implies nothing — the row is
+* already stamped, or it carried neither flag.
+*
+* Both legacy flags fold to `readonly`, which is the CONSERVATIVE direction: a
+* state change must never start deleting footage on its own, and it must never
+* make footage that was still being served disappear. `enabled: false` used to
+* leave the location evictable under pressure; folding it to `readonly` stops
+* that, which is a strictly safer answer than the one it replaces.
+*/
+function legacyModeOf(location) {
+	if (location.mode !== void 0) return null;
+	if (location.config["readOnly"] === true) return "readonly";
+	if (location.enabled === false) return "readonly";
+	return null;
+}
+/**
+* The state of a location, stamped or folded. THE one interpretation: a row
+* that predates D385 is never ambiguous, and a stamped `mode` always wins over
+* whatever the legacy pair still says.
+*/
+function resolveLocationMode(location) {
+	return (isStorageLocationMode(location.mode) ? location.mode : void 0) ?? legacyModeOf(location) ?? "active";
+}
+/** Is this one of the four states? The stamped value crosses a wire, and a
+*  value nobody defined must not be rendered as if it were a state. */
+function isStorageLocationMode(value) {
+	return STORAGE_LOCATION_MODES.some((mode) => mode === value);
+}
+/** May this location be written to? */
+function mayWriteToLocation(location) {
+	return modeMayWrite(resolveLocationMode(location));
+}
 /**
 * `StorageLocationType` — an addon-declared id that identifies the *kind* of
 * storage a location serves. Defined here (not in `capabilities/storage.cap.ts`)
@@ -21875,7 +21955,11 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).rea
 	ownerType: EventOwnerTypeSchema,
 	eventId: number().int(),
 	deviceId: number()
-}), array(MediaFileInfoSchema).readonly()), method(SearchObjectEventsInput, array(ScoredObjectEventSchema).readonly()), method(object({}), WipeObjectEmbeddingsResultSchema, {
+}), array(MediaFileInfoSchema).readonly()), method(object({
+	deviceId: number(),
+	ownerKind: MediaPresenceOwnerKindSchema,
+	ownerIds: array(string()).max(5e3)
+}), array(string()).readonly()), method(SearchObjectEventsInput, array(ScoredObjectEventSchema).readonly()), method(object({}), WipeObjectEmbeddingsResultSchema, {
 	kind: "mutation",
 	auth: "admin"
 }), method(RebuildObjectEmbeddingsInput, RebuildObjectEmbeddingsResultSchema, {
@@ -24869,6 +24953,18 @@ method(VectorDeclareIndexInputSchema, _void(), {
 	kind: "mutation",
 	auth: "admin"
 }), method(VectorStatsInputSchema, VectorStatsResultSchema, { auth: "admin" });
+_enum([
+	"queue-full",
+	"camera-backoff",
+	"sleeping",
+	"camera-refused",
+	"no-keyframe",
+	"no-catalog-row",
+	"unsupported",
+	"unknown-device",
+	"uid-missing"
+]);
+_enum(["deferred", "final"]);
 var ClipSchema = object({
 	/** Opaque, provider-namespaced id. The default provider encodes the time
 	*  window so `getClipPlayback` is self-contained (no event re-query). */
@@ -24943,31 +25039,454 @@ var ClipSchema = object({
 	holes: array(object({
 		startMs: number(),
 		endMs: number()
-	})).optional()
+	})).optional(),
+	/**
+	* A URL that MAY produce this clip's still, asked only for rows actually on
+	* screen. The opposite of {@link ClipSchema.thumbnail}: that one is VOUCHED
+	* (a JPEG is already on disk), this one is an offer. The route answers 200
+	* with the image, or 204 with `x-camstack-reason` when it could not mint one
+	* — a surface latches that refusal to the instant rather than retrying.
+	*
+	* Never both: a clip with a vouched `thumbnail` needs no mint.
+	*/
+	thumbnailMint: string().optional(),
+	/**
+	* Why no still will be produced for this clip RIGHT NOW — set when the
+	* provider already knows, so the surface draws the glyph and the reason
+	* instead of firing a mint that cannot succeed.
+	*
+	* `sleeping` — a standalone battery camera; a read would be a wake (D549 4).
+	* `camera-refused` — the camera answered the CoverPreview with a refusal.
+	* `no-keyframe` — the window holds no decodable I-frame (an event that sits
+	*   inside no file is the measured case).
+	* `unsupported` — this source cannot mint stills at all.
+	*/
+	thumbnailUnavailable: object({ reason: _enum([
+		"sleeping",
+		"camera-refused",
+		"no-keyframe",
+		"unsupported"
+	]) }).optional(),
+	/**
+	* When the catalog this row came from was last CONFIRMED against the device.
+	* Absent means "this row was read live". A persisted catalog served while a
+	* camera sleeps carries the age it really has — a cached list is never drawn
+	* as current (D549 13).
+	*/
+	catalogAsOf: number().optional(),
+	/**
+	* The camera's OWN type strings for this clip, all of them, unmapped
+	* (`md`, `people`, `dog_cat`, `sched`, …). Kept beside {@link labels}
+	* because a firmware inventing a type must not vanish: the mapping into our
+	* filter vocabulary is lossy on purpose and this is the lossless copy
+	* (D549 20).
+	*/
+	nativeTypes: array(string()).optional(),
+	/**
+	* What the subject DID — `crossline`, `intrude`, `loitering`. A behaviour
+	* travels BESIDE a class, never instead of one, and the class filter ignores
+	* it: "a person crossed a line" is still a person (D549 20).
+	*/
+	behaviours: array(string()).optional(),
+	/**
+	* The same recording as two files — the sub twin (what the row and its
+	* thumbnail are) and its main twin, matched at listing time so a quality
+	* change never re-searches the camera (D549 15). `getClipPlayback`'s
+	* `profile` picks between them: `low | mid` → sub, `high` → main.
+	*/
+	streams: object({
+		sub: object({
+			id: string(),
+			bytes: number().optional()
+		}).optional(),
+		main: object({
+			id: string(),
+			bytes: number().optional()
+		}).optional()
+	}).optional(),
+	/** The camera says it holds a sub-stream copy of this recording. */
+	supportSub: boolean().optional(),
+	/**
+	* Whether this row has bytes behind it. ABSENT means yes — every clip that
+	* IS a file is playable, and only a source that lists EVENTS can produce a
+	* row with nothing to play (the measured case: 1 of 29 hub events on 3628
+	* fell inside no file). Such a row is shown, never dropped and never offered
+	* as playable-then-failing (D549 19).
+	*/
+	playable: boolean().optional(),
+	/** Why {@link playable} is false, verbatim (`no-file-for-window`). */
+	unplayableReason: string().optional(),
+	/**
+	* This clip is STILL BEING WRITTEN, so {@link ClipSchema.timeRange}`.endMs`
+	* is not its end.
+	*
+	* Absent — the common case — means the row is closed and its `endMs` is the
+	* end of the recording. Present and `true` means the source told us the file
+	* has no end yet, and the `endMs` we carry is whatever the camera's index
+	* entry happened to hold: on a Reolink E1 Outdoor PoE (592, measured
+	* 2026-09-20) the newest file `…_192927_000000_…_0.mp4` reported an `endTime`
+	* of 19:29:56 and STILL reported it eight minutes later, while the file went
+	* on growing. A surface that drew 29 s there was lying about a clip that
+	* plays for minutes, on the one row the operator looks at first.
+	*
+	* `endMs` is deliberately still a number: it is the best bound anything has
+	* for a mint window or a byte fetch, and every consumer already requires it.
+	* This flag says what it is WORTH, and a duration is not drawn from it.
+	*/
+	inProgress: boolean().optional()
 });
 var ClipPlaybackSchema = object({
-	/** HLS master URL through the hub data-plane (Range + token in path). */
+	/**
+	* A media URL through the hub data-plane. {@link ClipPlaybackSchema.format}
+	* says what kind — an HLS master playlist for a recording-derived clip, a
+	* progressive MP4 for a native file the vendor addon muxed and serves with
+	* `Range`. The URL is NOT a credential: both planes are registered
+	* `access: 'authenticated'` and the hub's `/addon/<id>/<prefix>` proxy takes
+	* the session cookie, so nothing is appended to it (D549 22).
+	*/
 	playbackUrl: string(),
+	/**
+	* How to play {@link playbackUrl}. Absent means `hls` — the shape every
+	* existing consumer already assumes. A player that branches on this is the
+	* one change a native clip needs; a player that ignores it will hand an MP4
+	* to hls.js and fail parsing it as a manifest.
+	*/
+	format: _enum(["hls", "mp4"]).optional(),
+	/**
+	* Which twin was actually served. A clip that holds only one stream answers
+	* with the one it has, and the surface SAYS so — a missing main twin is
+	* never served silently as if it were the asked-for quality (D549 15).
+	*/
+	served: CamProfileSchema.optional(),
 	/** Optional LAN/remote alternates for the same clip. */
 	playbackEndpoints: array(string()).optional(),
 	token: string().optional()
 });
-DeviceType.Camera, method(object({
-	deviceId: number(),
-	since: number(),
-	until: number(),
-	limit: number().int().positive().optional()
-}), array(ClipSchema).readonly(), {
-	kind: "query",
-	auth: "admin"
-}), method(object({
-	deviceId: number(),
-	clipId: string()
-}), ClipPlaybackSchema, {
-	kind: "query",
-	auth: "admin"
+/**
+* Why a source cannot answer right now — per SOURCE, never fleet-wide.
+*
+* `ok` is the only state whose clip list may be read as complete. The other
+* three exist because an empty list from a sleeping camera reads as "this
+* camera has no recordings", which is the defect this whole line of work is
+* about: a battery camera nobody woke (`sleeping`), a camera that could not be
+* reached at all (`unreachable`, also what a provider that THREW reports), a
+* camera whose SD card is not mounted (`no-storage`, measured on 640 —
+* `HddInfo mount 0`, honestly nothing to list rather than "no clips"), and a
+* camera whose OWN index disagrees with its OWN calendar (`index-empty`,
+* measured on 618: the calendar marks 3–20 September, days 6–20 list zero
+* files on both streams and both filters, with 177 GB free). That last one is
+* a defect ON THE CAMERA, and the only honest thing a provider can do is say
+* 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",
+		"sleeping",
+		"unreachable",
+		"no-storage",
+		"index-empty"
+	]),
+	/** Free text, shown verbatim. Names the camera's own refusal when there is one. */
+	reason: string().optional(),
+	/** When this source's catalog was last CONFIRMED. A cached list is never
+	*  drawn as current: the surface shows the age whenever it is older than the
+	*  refresh interval. */
+	catalogAsOf: number().optional()
 });
 /**
+* One SOURCE of clips for a camera — a row of the picker, and the namespace
+* every clip id from it is prefixed with (`analytics`,
+* `native:reolink:onboard`, `hksv`, …).
+*
+* A provider lists the sources IT serves for that device, and answers for each
+* of them whether it can answer at all. A provider with nothing to offer on a
+* camera returns `[]` — it is not that camera's business.
+*/
+var ClipSourceSchema = object({
+	/** The value this source stamps on {@link ClipSchema.source}, and the prefix
+	*  of every clip id it mints. `getClipPlayback` routes on it. */
+	source: string(),
+	/** Operator-facing name of the source ("CamStack recordings", "SD card"). */
+	label: string(),
+	/**
+	* The addon that SERVES this row.
+	*
+	* A surface cannot otherwise resolve a source to who answers it, and the
+	* alternative — a `native:reolink:* → provider-reolink` table inside the
+	* widget — is a second authority on provider identity living in the one
+	* package with no business knowing it, wrong the day a third source appears
+	* (D557). One addon may serve SEVERAL sources, which is why the per-device
+	* switch is keyed by SOURCE and not by this (D555) — `addon-provider-reolink`
+	* served a hub child two of them until the two views were measured to be one
+	* store read twice (D555) and then read ONE way (D565).
+	*
+	* Optional for version skew only. The collection dispatcher stamps it from
+	* the registry, so a row that travelled through the fan-out carries the
+	* authoritative id whatever the provider filled in.
+	*/
+	addonId: string().optional(),
+	availability: ClipSourceAvailabilitySchema
+});
+var videoclipsCapability = {
+	name: "videoclips",
+	scope: "device",
+	mode: "collection",
+	kind: "wrapper",
+	defaultActive: true,
+	/** A clip is a window over a camera's footage — the cap is meaningless on a
+	*  sensor, a button or an event emitter, and the `defaultActive` auto-bind
+	*  reads this to decide which devices it may claim. */
+	deviceTypes: [DeviceType.Camera],
+	/**
+	* The Clips section of a camera's device details is FRAMEWORK-DERIVED (D14):
+	* the aggregator turns this declaration into the `type:'widget'` section and
+	* `DeviceDetail.tsx` is never edited. `videoclips` is the first WRAPPER cap
+	* to declare one — every previous `host/` widget cap is `deviceNative` — so
+	* `device-config-widget-wrapped-binding.spec.ts` pins that a `kind:'wrapped'`
+	* binding entry derives the same section a native one does.
+	*
+	* **It is a SECTION of the Recording tab, at the end of it — not a tab of
+	* its own.** It shipped as a `clips` top-tab and the operator rejected the
+	* placement: *"utilizzerei la stessa tab recordings, lì abbiamo già tutto il
+	* necessario, una nuova sezione alla fine per le clips"*. The Recording tab
+	* already holds the recorder's panel, the schedule bands and the unified
+	* retention policy; footage the camera itself holds is the same question,
+	* asked of a different store. `order: 100` puts it after all of them with
+	* room left in front. The `clips` entry in `WELL_KNOWN_TABS` went with it —
+	* a well-known id nobody declares is an invitation to mint the tab again.
+	*
+	* `topTab` stays: the browser owns a pane (a day's tiles, a source list and
+	* a player) and the Config tab's inner bar has no room for one. The widget
+	* itself is `host/clips-browser` in ui-library's `HOST_WIDGETS`, and because
+	* the admin Recordings page renders every `location:'top-tab'` +
+	* `tab:'recording'` section behind its camera picker
+	* (`CameraRecordingSettingsSection`), this declaration lands the section on
+	* BOTH surfaces with no second wiring.
+	*/
+	deviceConfig: { ui: {
+		kind: "widget",
+		widgetId: "host/clips-browser",
+		tab: "recording",
+		topTab: true,
+		label: "Clips",
+		order: 100
+	} },
+	methods: {
+		listClips: method(object({
+			deviceId: number(),
+			since: number(),
+			until: number(),
+			limit: number().int().positive().optional(),
+			/**
+			* WHICH provider to ask — the `addonId` a {@link ClipSourceSchema} row
+			* carries, never a source id and never a list. **Required** (D554 amended).
+			*
+			* A provider the device is not bound to is refused by name rather than
+			* answered by another one (D552's `rejectUnresolvedAddonPin` rule).
+			*
+			* It was optional, documented as "absent means the device's BOUND
+			* provider, which is CamStack on every camera". No code implemented
+			* that. Measured on the live hub 2026-09-20 — device 592, bound to
+			* `recorder` AND `provider-reolink` — a bare call with `limit: 3`
+			* answered SIX rows, three from each source, merged newest-first:
+			* `device-collection-dispatch.ts` simply left the fan-out un-narrowed,
+			* so absence bought the union this method exists not to be, and
+			* `limit` meant `limit × sources`.
+			*
+			* There is nothing to restore the default to. `getBindings` answers a
+			* collection cap with a DERIVED, PLURAL set (D554 amended, step 0);
+			* `setWrapperActive` — the singleton authority that could name one —
+			* throws for a collection cap by design. Naming CamStack here instead
+			* would privilege one addon by id inside a surface whose premise is
+			* that sources are peers, and would be wrong on the first camera with
+			* no recorder binding. So absence is REFUSED, in the schema, where the
+			* generated types make it unomittable rather than merely discouraged.
+			*
+			* The default belongs to the SURFACE, which has the `listSources` rows
+			* and can say which one it picked (D569 § 1–3; the viewer already
+			* always sends this).
+			*
+			* It replaced `sources?: string[]`, a VIEW filter over source ids that
+			* assumed the answer was a fan-out over everything a camera has. The
+			* operator settled otherwise on 2026-09-20 — *"l'utilizzatore è uno
+			* solo"* — so the list is asked of one provider at a time and there is
+			* nothing to filter out of it.
+			*/
+			provider: string().min(1)
+		}), array(ClipSchema).readonly(), {
+			kind: "query",
+			auth: "protected"
+		}),
+		/**
+		* The sources this camera has, WITH the reason any of them cannot answer.
+		*
+		* Asked separately from `listClips` because an empty clip list is
+		* ambiguous and this is the only place the ambiguity is resolved: every
+		* bound provider contributes its own rows, and a provider that could not
+		* be reached at all still produces one row saying so. A surface that draws
+		* "no clips" without reading this is drawing a guess.
+		*/
+		listSources: method(object({ deviceId: number() }), array(ClipSourceSchema).readonly(), {
+			kind: "query",
+			auth: "protected"
+		}),
+		getClipPlayback: method(object({
+			deviceId: number(),
+			clipId: string(),
+			/**
+			* Which twin to serve, on the ONE quality scale the system already has
+			* (`CamProfileSchema`). `low | mid` → the sub file, `high` → the main
+			* twin; both ids are already on the row so this never re-searches the
+			* camera. Absent means the provider's own default (the sub file, which
+			* every source is measured to hold).
+			*
+			* `auto` is deliberately NOT accepted here: a stored file has no
+			* broker session, so the adaptive tier cannot be resolved for it. The
+			* viewer resolves `auto` to a profile the same way live does, before
+			* it calls (D549 15).
+			*/
+			profile: CamProfileSchema.optional()
+		}), 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"
+		})
+	}
+};
+/**
 * 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`
@@ -30934,13 +31453,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. */
@@ -30957,6 +31564,18 @@ 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"
+]);
 /** Candidate download URLs (LAN first, then operator extra hosts). */
 var ExportDownloadSchema = object({
 	url: string(),
@@ -30975,16 +31594,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"]
@@ -36405,6 +37058,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.ownersWithMedia": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.pauseForStorageMigration": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -38997,6 +39656,18 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"videoclips.listSources": {
+		capName: "videoclips",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"videoclips.readClipBytes": {
+		capName: "videoclips",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"viewerUi.getStaticDir": {
 		capName: "viewer-ui",
 		capScope: "system",
@@ -40299,6 +40970,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"pipelineAnalytics.ownersWithMedia": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"pipelineAnalytics.proposeRetrainAnnotations": [{
 		name: "deviceId",
 		form: "single",
@@ -41005,6 +41681,16 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"videoclips.listSources": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
+	"videoclips.readClipBytes": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"waterHeater.setAway": [{
 		name: "deviceId",
 		form: "single",
@@ -88769,6 +89455,410 @@ function firstExposedAccessorySetupUri(exposed, logger) {
 	}
 }
 //#endregion
+//#region src/hksv/build-outcome.ts
+/**
+* Every camera's last build verdict, in this process.
+*
+* A `Map` behind a named type rather than a bare one, because the thing that
+* matters about it is what `get` returning `undefined` MEANS: not "recording is
+* fine", but "no accessory has been built for this camera since the addon
+* started".
+*/
+var HksvBuildOutcomes = class {
+	byDevice = /* @__PURE__ */ new Map();
+	note(outcome) {
+		this.byDevice.set(outcome.deviceId, outcome);
+	}
+	/** `null` when nothing has been established for this camera yet. */
+	lastFor(deviceId) {
+		return this.byDevice.get(deviceId) ?? null;
+	}
+	/** The camera left HomeKit: its verdict is not a fact about anything now. */
+	forget(deviceId) {
+		this.byDevice.delete(deviceId);
+	}
+};
+//#endregion
+//#region src/hksv/clip-ffmpeg-run.ts
+function createBoundedFfmpegRunner(input) {
+	return (args) => new Promise((resolve) => {
+		let settled = false;
+		const finish = (run) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve(run);
+		};
+		const child = input.spawnFn(input.ffmpegBinaryPath, [...args], { stdio: [
+			"ignore",
+			"ignore",
+			"pipe"
+		] });
+		let stderr = "";
+		child.stderr?.on("data", (chunk) => {
+			if (stderr.length < 2e3) stderr += chunk.toString("utf8");
+		});
+		const timer = setTimeout(() => {
+			child.kill("SIGKILL");
+			finish({
+				code: null,
+				timedOut: true,
+				spawnFailed: false,
+				stderr
+			});
+		}, input.timeoutMs);
+		timer.unref?.();
+		child.on("error", (err) => {
+			finish({
+				code: null,
+				timedOut: false,
+				spawnFailed: true,
+				stderr: err.message
+			});
+		});
+		child.on("close", (code) => {
+			finish({
+				code,
+				timedOut: false,
+				spawnFailed: false,
+				stderr
+			});
+		});
+	});
+}
+//#endregion
+//#region src/hksv/clip-location.ts
+/** The declared id. Deployment-wide; see the docblock for why it is new. */
+var HOMEKIT_CLIPS_LOCATION_TYPE = "homekitClips";
+/** The class subtree under the resolved root. Never written at the root (D327). */
+var HOMEKIT_CLIPS_SUBTREE = "homekit-clips";
+/**
+* The cap calls, HERE and not in the addon.
+*
+* Deliberately co-located with the `mayWriteToLocation` filter below: a file
+* that enumerates storage locations must visibly decide whether it is choosing
+* a WRITE target (`scripts/check-storage-write-target-enabled.ts` enforces
+* exactly that, and it fired when the closure lived in the addon). Splitting
+* the enumeration from the decision is how the backup fan-out grew a second
+* enabled flag.
+*/
+function createClipLocationPorts(api) {
+	return {
+		listLocations: () => api.storage.listLocations.query({}),
+		resolvePath: (locationId) => api.storage.resolve.query({
+			location: locationId,
+			relativePath: ""
+		})
+	};
+}
+var HksvClipLocation = class {
+	input;
+	log;
+	now;
+	revalidateMs;
+	cachedRoot = null;
+	resolvedAt = Number.NEGATIVE_INFINITY;
+	refusal = null;
+	/** What the last warn said, so a per-clip refusal is not a per-clip log line. */
+	announced = null;
+	inFlight = null;
+	constructor(input) {
+		this.input = input;
+		this.log = input.logger;
+		this.now = input.now ?? Date.now;
+		this.revalidateMs = input.revalidateMs ?? 6e4;
+	}
+	/** Why the last resolution produced no root. `null` once one succeeded. */
+	get lastRefusal() {
+		return this.refusal;
+	}
+	/** The doorbell rang (`StorageLocationsChanged`): drop the mirror. */
+	invalidate() {
+		this.resolvedAt = Number.NEGATIVE_INFINITY;
+	}
+	/**
+	* The directory clips are written under, or `null` when there is none right
+	* now. Never throws: the caller's correct move for every refusal is the same
+	* — do not tee this clip, and leave HomeKit alone.
+	*/
+	async root() {
+		if (this.now() - this.resolvedAt < this.revalidateMs) return this.cachedRoot;
+		const inflight = this.inFlight;
+		if (inflight !== null) return inflight;
+		const attempt = this.resolve();
+		this.inFlight = attempt;
+		try {
+			return await attempt;
+		} finally {
+			this.inFlight = null;
+		}
+	}
+	async resolve() {
+		try {
+			const rows = (await this.input.ports.listLocations()).filter((l) => l.type === HOMEKIT_CLIPS_LOCATION_TYPE);
+			if (rows.length === 0) return this.refuse("no-location", {});
+			if (rows.length > 1) this.warnOnce("hksv clip store: more than one HomeKit clips location exists — it is declared single", { ids: rows.map((l) => l.id) });
+			const writable = rows.find((l) => mayWriteToLocation(l));
+			if (writable === void 0) {
+				const first = rows[0];
+				return this.refuse("not-writable", {
+					locationId: first?.id ?? null,
+					mode: first === void 0 ? null : resolveLocationMode(first)
+				});
+			}
+			const root = `${(await this.input.ports.resolvePath(writable.id)).replace(/\/+$/, "")}/${HOMEKIT_CLIPS_SUBTREE}`;
+			this.cachedRoot = root;
+			this.resolvedAt = this.now();
+			this.refusal = null;
+			if (this.announced !== null) {
+				this.announced = null;
+				this.log.info("hksv clip store: the clips location is writable again", { meta: {
+					locationId: writable.id,
+					root
+				} });
+			}
+			return root;
+		} catch (err) {
+			return this.refuse("unreachable", { error: err instanceof Error ? err.message : String(err) });
+		}
+	}
+	refuse(reason, meta) {
+		this.cachedRoot = null;
+		this.resolvedAt = this.now();
+		this.refusal = reason;
+		this.warnOnce("hksv clip store: no writable HomeKit clips location — clips are NOT being kept (HomeKit recording is unaffected)", {
+			reason,
+			...meta
+		});
+		return null;
+	}
+	/**
+	* One line per distinct situation. A refusal that reprinted on every clip
+	* would drown the line that says it CHANGED, and the operator reads the log
+	* to find out which of the two is happening.
+	*/
+	warnOnce(message, meta) {
+		const key = `${message}|${JSON.stringify(meta)}`;
+		if (this.announced === key) return;
+		this.announced = key;
+		this.log.warn(message, { meta });
+	}
+};
+//#endregion
+//#region src/hksv/clip-remux.ts
+/**
+* The faststart pass: the teed clip is made SEEKABLE, once, by the process that
+* minted it.
+*
+* ## Why the producer owes this
+*
+* The tee cuts like a pipe. ffmpeg writes `frag_keyframe+empty_moov` and never
+* returns to write a trailer, so on a teed clip `mvhd.duration` and
+* `mdhd.duration` are **0**, the `stbl` sample tables are EMPTY and there is no
+* `mfra`. Measured, on this hub's own files. The result decodes end to end — it
+* plays — but nothing can map a time to a byte in it, and a time-to-byte map is
+* the whole of what a scrub, a `Range` request and a stated duration are.
+*
+* The alternative was a remux in the CONSUMER, at play time. That puts an
+* ffmpeg per viewer in the broker's runner and buffers the whole file to write
+* a trailer, every time anybody drags — the cost D570 § 5(b) rejected, moved
+* one process along. Here it is one pass per clip, at the moment the clip is
+* born, measured at 40 ms and +0.7 % bytes. A clip is written once and read
+* many times; this is the side of that asymmetry the work belongs on.
+*
+* ## The constraint that outranks the feature
+*
+* Exactly as for the tee itself: **a clip that does not seek is a clip; a clip
+* the remux ate is a HomeKit recording the operator lost.** So the pass writes
+* a SIBLING and renames over the original only once it has vouched for it, it
+* never throws, and every way of failing has its own name on the record —
+* a missing binary, a deadline and a file ffmpeg blessed but did not fix are
+* three different operator actions.
+*
+* ## The vouch is a measurement, not an exit code
+*
+* `-movflags +faststart` exiting 0 is not evidence. {@link moovPrecedesMdat}
+* reads the top-level box order off the produced file and requires `moov`
+* ahead of the media — and requires the file to be PROGRESSIVE, because the
+* fragmented shape the tee already wrote is *also* moov-first and is exactly
+* what this pass exists to replace.
+*/
+/** A remux that has not finished by here is not going to. */
+var CLIP_REMUX_TIMEOUT_MS = 3e4;
+/** The sibling the pass writes before it has earned the clip's own name. */
+var CLIP_REMUX_SUFFIX = ".faststart";
+/**
+* How much of the head is read back to judge the box order. The `moov` of a
+* short clip is a few hundred KB at most, and this only has to reach far enough
+* to meet the first `mdat` or `moof`.
+*/
+var HEAD_BYTES = 1024 * 1024;
+function buildClipRemuxArgs(input) {
+	return [
+		"-hide_banner",
+		"-loglevel",
+		"error",
+		"-nostdin",
+		"-y",
+		"-i",
+		input.clipPath,
+		"-c",
+		"copy",
+		"-movflags",
+		"+faststart",
+		"-f",
+		"mp4",
+		input.outPath
+	];
+}
+function createClipRemuxer(input) {
+	return async ({ clipPath }) => {
+		const outPath = `${clipPath}${CLIP_REMUX_SUFFIX}`;
+		try {
+			const run = await input.runner(buildClipRemuxArgs({
+				clipPath,
+				outPath
+			}));
+			if (run.spawnFailed) return await discard(outPath, "ffmpeg-missing");
+			if (run.timedOut) return await discard(outPath, "timed-out");
+			if (run.code !== 0) return await discard(outPath, "remux-failed");
+			const size = await sizeOf(outPath);
+			if (size === null || size === 0) return await discard(outPath, "remux-failed");
+			const head = await readHead(outPath);
+			if (!moovPrecedesMdat(head)) return await discard(outPath, "not-seekable");
+			const durationMs = readMovieDurationMs(head);
+			await rename(outPath, clipPath);
+			return {
+				ok: true,
+				bytes: size,
+				...durationMs === null ? {} : { durationMs }
+			};
+		} catch {
+			return await discard(outPath, "remux-failed");
+		}
+	};
+}
+async function discard(outPath, reason) {
+	await rm(outPath, { force: true }).catch(() => void 0);
+	return {
+		ok: false,
+		reason
+	};
+}
+async function sizeOf(path) {
+	try {
+		return (await stat(path)).size;
+	} catch {
+		return null;
+	}
+}
+async function readHead(path) {
+	const buf = await readFile(path);
+	return new Uint8Array(buf.buffer, buf.byteOffset, Math.min(buf.byteLength, HEAD_BYTES));
+}
+/**
+* Does this file carry a progressive index ahead of its media?
+*
+* Walks the TOP-LEVEL boxes only. Three verdicts collapse into `false`, and
+* each of them is a real file this store has held:
+*
+*  - `moov` after `mdat` — a plain mux, seekable only once the whole file is
+*    in hand, which over a `Range` reader means never.
+*  - `moof` before any `mdat` — the FRAGMENTED shape the tee writes. Its
+*    leading `moov` is the empty one `empty_moov` produced, so judging on
+*    position alone would bless exactly the file this pass replaces.
+*  - anything unreadable — a truncated header, or a box claiming a size that
+*    does not advance the cursor. A corrupt file is never guessed at, and a
+*    non-advancing size is how a scanner spins for ever.
+*/
+function moovPrecedesMdat(bytes) {
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	let at = 0;
+	let sawMoov = false;
+	while (at + 8 <= bytes.byteLength) {
+		const declared = view.getUint32(at);
+		const type = String.fromCharCode(bytes[at + 4], bytes[at + 5], bytes[at + 6], bytes[at + 7]);
+		let size = declared;
+		let header = 8;
+		if (declared === 1) {
+			if (at + 16 > bytes.byteLength) return false;
+			const large = view.getBigUint64(at + 8);
+			if (large > BigInt(Number.MAX_SAFE_INTEGER)) return false;
+			size = Number(large);
+			header = 16;
+		}
+		if (size < header) return false;
+		if (type === "moov") sawMoov = true;
+		if (type === "mdat") return sawMoov;
+		if (type === "moof") return false;
+		at += size;
+	}
+	return false;
+}
+/**
+* The movie duration, in ms, from the `mvhd` inside `moov`.
+*
+* `null`, never `0`, for every way of not knowing — no `moov`, no `mvhd`, a
+* truncated header, a zero timescale, or the **zero duration `empty_moov`
+* writes**, which is the case that matters: believing it would replace a
+* duration that is merely wrong with one that confidently says the clip is
+* empty (D393).
+*
+* Worth having because the alternative number is wrong in a specific,
+* measurable way: `endedAtMs - startedAtMs` is how long the TEE ran, and the
+* first fragments it wrote were the prebuffer — footage older than the tee
+* itself. On 615 that is 12.0 s claimed against 19.99 s held.
+*/
+function readMovieDurationMs(bytes) {
+	const moov = findTopLevelBox(bytes, "moov");
+	if (moov === null) return null;
+	const mvhd = findTopLevelBox(moov, "mvhd");
+	if (mvhd === null || mvhd.byteLength < 4) return null;
+	const view = new DataView(mvhd.buffer, mvhd.byteOffset, mvhd.byteLength);
+	const version = mvhd[0];
+	const timescaleAt = version === 1 ? 20 : 12;
+	const durationAt = timescaleAt + 4;
+	if (durationAt + (version === 1 ? 8 : 4) > mvhd.byteLength) return null;
+	const timescale = view.getUint32(timescaleAt);
+	if (timescale === 0) return null;
+	const duration = version === 1 ? Number(view.getBigUint64(durationAt)) : view.getUint32(durationAt);
+	if (duration <= 0 || !Number.isFinite(duration)) return null;
+	return Math.round(duration / timescale * 1e3);
+}
+/**
+* The PAYLOAD — header stripped — of the first top-level box of `type`, or
+* `null`. Stripped, because the only reason to hold a box here is to walk its
+* children, and leaving the header on makes the first child look like the
+* parent.
+*
+* Deliberately the same walk as {@link moovPrecedesMdat} rather than a shared
+* generator: that one answers a question about ORDER and stops at the media,
+* this one descends. Both refuse a box that does not advance the cursor, which
+* is the property neither can do without.
+*/
+function findTopLevelBox(bytes, type) {
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	let at = 0;
+	while (at + 8 <= bytes.byteLength) {
+		const declared = view.getUint32(at);
+		const found = String.fromCharCode(bytes[at + 4], bytes[at + 5], bytes[at + 6], bytes[at + 7]);
+		let size = declared;
+		let header = 8;
+		if (declared === 1) {
+			if (at + 16 > bytes.byteLength) return null;
+			const large = view.getBigUint64(at + 8);
+			if (large > BigInt(Number.MAX_SAFE_INTEGER)) return null;
+			size = Number(large);
+			header = 16;
+		}
+		if (size < header) return null;
+		const end = Math.min(at + size, bytes.byteLength);
+		if (found === type) return at + header >= end ? null : bytes.subarray(at + header, end);
+		at += size;
+	}
+	return null;
+}
+//#endregion
 //#region src/hksv/clip-record.ts
 /**
 * What ONE teed HomeKit clip is, on disk.
@@ -88790,10 +89880,14 @@ function firstExposedAccessorySetupUri(exposed, logger) {
 *   `deriveFragmentLengthMs` refuses a GOP longer than 8 s. A camera the tee
 *   never writes for is not a gap in this store, it is a camera HKSV never
 *   recorded; {@link HksvClipRecord} exists only for the ones it did.
-* - **The duration is whatever iOS PULLED.** `durationMs` is the wall-clock
-*   span of the HDS stream (prebuffer replay plus however long the hub kept it
-*   open), not a window CamStack chose. A short clip is not a truncated one —
-*   {@link HksvClipRecord.truncated} is the only thing that says truncated.
+* - **The duration is whatever iOS PULLED.** Not a window CamStack chose, and
+*   a short clip is not a truncated one — {@link HksvClipRecord.truncated} is
+*   the only thing that says truncated. Since D578 it is READ FROM THE FILE
+*   (`mvhd`, after the faststart pass), because the tee's own wall clock is
+*   wrong in a specific direction: the clock starts when the tee does, and the
+*   first fragments it writes are the PREBUFFER — footage older than the tee
+*   itself. Measured on 615: 12.0 s claimed against 19.99 s held. The wall
+*   clock remains the fallback for a file that could not be measured.
 *
 * ## `thumbnailFile` is VOUCHED
 *
@@ -88812,6 +89906,18 @@ var HksvThumbnailUnavailableReasonSchema = _enum([
 	"no-init-segment",
 	"not-attempted"
 ]);
+/**
+* Why a teed clip could not be made seekable. Named, never blank — a missing
+* binary, a deadline and a file ffmpeg blessed but did not fix are three
+* different operator actions, and "it does not seek" is none of them.
+*/
+var HksvRemuxUnavailableReasonSchema = _enum([
+	"remux-failed",
+	"timed-out",
+	"ffmpeg-missing",
+	"not-seekable",
+	"not-attempted"
+]);
 /** Why a clip stopped short of the stream that fed it. */
 var HksvClipTruncationSchema = _enum([
 	"size-cap",
@@ -88830,21 +89936,59 @@ var HksvClipRecordSchema = object({
 	streamId: number().int(),
 	startedAtMs: number().int(),
 	endedAtMs: number().int(),
-	/** `endedAtMs - startedAtMs`. What iOS pulled, never a window we chose. */
+	/**
+	* What iOS pulled, never a window we chose — measured from the file's own
+	* `mvhd` where the faststart pass could read it, and `endedAtMs -
+	* startedAtMs` otherwise. See the docblock: the two differ by the prebuffer.
+	*/
 	durationMs: number().int().nonnegative(),
 	/** How much of the clip's head came from the prebuffer ring, by ARRIVAL age. */
 	prebufferSpanMs: number().int().nonnegative(),
+	/**
+	* The size of {@link HksvClipRecord.file} AS IT NOW STANDS on disk — so on a
+	* clip the faststart pass rewrote, the post-remux size, re-stat'd and never
+	* carried over from the tee's own count. The pass costs about +0.7 %, and a
+	* record stating the pre-remux figure would be wrong by exactly that for
+	* ever, on the one field a `Range` reader and the disk accounting both use.
+	*/
 	bytes: number().int().nonnegative(),
 	fragments: number().int().nonnegative(),
 	/** Basenames, relative to the clip's own device directory. */
 	file: string().min(1),
 	thumbnailFile: string().min(1).optional(),
 	thumbnailUnavailable: object({ reason: HksvThumbnailUnavailableReasonSchema }).optional(),
+	/**
+	* The faststart pass ran and its output was VOUCHED: `moov` ahead of the
+	* media, progressive, read back off the produced file. Present only when
+	* that is true of {@link HksvClipRecord.file}.
+	*
+	* Three states, not two, and the third is the reason this is optional rather
+	* than a boolean: `true` means it seeks, {@link
+	* HksvClipRecord.remuxUnavailable} means it does not and says why, and
+	* NEITHER means unknown — a sidecar written before this field existed cannot
+	* be given one after the fact, and a reader must not read that silence as
+	* "does not seek" (D393).
+	*/
+	seekable: literal(true).optional(),
+	remuxUnavailable: object({ reason: HksvRemuxUnavailableReasonSchema }).optional(),
 	truncated: HksvClipTruncationSchema.optional(),
 	/** iOS sent `ack` for this stream: HomeKit itself kept the clip. */
 	acknowledgedByHomeKit: boolean(),
 	width: number().int().positive(),
 	height: number().int().positive(),
+	/**
+	* WHICH broker slot HomeKit recorded from, on the one quality scale the
+	* system has (`high | mid | low`).
+	*
+	* Written by the tee from `pickRecordingSource`'s choice, because it is the
+	* only thing that knows: the pixels do not say which profile produced them,
+	* and a consumer that needs `served` (`getClipPlayback`, `readClipBytes`)
+	* must never derive it from the resolution. Optional because a sidecar
+	* written before this field existed cannot be given one after the fact — a
+	* reader REFUSES to name a twin it was never told (D393), rather than
+	* guessing one.
+	*/
+	profile: CamProfileSchema.optional(),
 	/** The advertised fragment length the source was cutting at. */
 	fragmentMs: number().int().positive()
 });
@@ -88853,7 +89997,17 @@ var HksvClipRecordSchema = object({
 * else, so a pruner deleting a clip never has to guess which JPEG was its.
 */
 function clipFileNames(clipId) {
-	const stem = clipStem(clipId);
+	return clipFileNamesForStem(clipStem(clipId));
+}
+/**
+* The same three names, from a stem a URL already carries.
+*
+* A data-plane route is handed the stem, not the id — `:` is legal on ext4 and
+* hostile in a path everywhere else, which is why {@link clipStem} exists — and
+* it must not re-derive the layout. One place mints these names, for both
+* callers.
+*/
+function clipFileNamesForStem(stem) {
 	return {
 		clip: `${stem}.mp4`,
 		thumbnail: `${stem}.jpg`,
@@ -88874,32 +90028,39 @@ function clipStem(clipId) {
 *
 * ## The owner
 *
-* The **export-hap addon**, in its OWN data dir, and nothing else. Not the
-* recorder's storage locations and not the `eventMedia` class:
+* The **export-hap addon**, on its own DECLARED storage location
+* (`homekitClips`, see `clip-location.ts`) — the operator picks the disk. Not
+* the `eventMedia` class and not `recordings`:
 *
-*  - `export-hap` is hub-only and runs in its own runner. The recorder's
-*    location machinery (D385/D386/D389) is another addon's, in another
-*    process, and reaching it would be a cross-runner write on the frame path
-*    of a live HomeKit session — exactly what D9/D18 forbid.
 *  - A teed clip is a DERIVED artifact of a HomeKit session, with no track, no
 *    detection and no event behind it. Filing it under `eventMedia` would put
 *    it inside the post-analysis retention sweep, where its lifetime would be
 *    decided by a policy written for a different question.
-*  - The precedent is D549 decision 13: Reolink's clip thumbnails live in the
-*    vendor addon's data dir under a per-device LRU, outside `eventMedia` and
-*    outside the sweep, for the same reason.
+*  - `recordings` rows belong to the recorder's placement planner, its evictor
+*    and its drain ratchet, and these files are not segments its index knows.
+*  - The precedent for a class of its own is D549 decision 13: Reolink's clip
+*    thumbnails sit outside `eventMedia` and outside the sweep for the same
+*    reason.
 *
-* Layout: `<dataDir>/hksv-clips/<deviceId>/<stem>.{mp4,jpg,json}`. One stem per
-* clip, three extensions, so a pruner deleting a clip never has to guess which
-* JPEG was its.
+* Layout: `<location root>/homekit-clips/<deviceId>/<stem>.{mp4,jpg,json}`. One
+* stem per clip, three extensions, so a pruner deleting a clip never has to
+* guess which JPEG was its; the `homekit-clips/` subtree is mandatory because
+* the location's seeded default SHARES the recordings root (D327).
 *
-* ## The retention, and why these numbers
+* The first cut wrote to `<dataDir>/hksv-clips/`. It was defensible and gave
+* the operator no say, which was the first thing he asked for after seeing it.
+*
+* ## The retention: one preference, three rails
 *
 * HomeKit's own retention is unreadable — HAP has no read-back, so CamStack can
 * never ask "does iOS still have this one?" and reconcile. The store therefore
 * cannot mirror HomeKit's lifetime and does not pretend to: it keeps a bounded
-* recent window and says, per clip, exactly when it started. Four bounds, all
-* enforced on every completion:
+* recent window and says, per clip, exactly when it started.
+*
+* **The AGE is the operator's, per camera**
+* ({@link HksvClipStoreInput.maxAgeMsFor}, cascaded global-default plus
+* per-device override by the addon), defaulting to 14 days. The other three are
+* RAILS, not preferences, and stay fixed:
 *
 *  - **{@link DEFAULT_CLIP_BOUNDS.maxClipBytes} per clip (256 MB).** A clip's
 *    duration is whatever iOS pulled — there is no window we choose — so this
@@ -88912,12 +90073,18 @@ function clipStem(clipId) {
 *    Both bounds exist for the same reason the prebuffer ring has both: at 4K
 *    a fragment is 6.35 MB, a 25x spread, and a count-only bound is a
 *    per-camera disk figure nobody can predict.
-*  - **{@link DEFAULT_CLIP_BOUNDS.maxAgeMs} (14 days)**, so a camera that
-*    stopped recording in March does not hold half a gigabyte forever.
 *  - **{@link DEFAULT_CLIP_BOUNDS.maxStoreBytes} (4 GB)** across every camera,
 *    applied after the per-device pass. Per-device bounds alone multiply by a
 *    camera count the operator changes without thinking about this store.
 *
+* An operator able to set the first to zero could turn the tee into a silent
+* no-op, and one able to raise the last without limit could fill the disk; the
+* age changes neither. The consequence is stated rather than left to be
+* discovered: a retention LONGER than the rails allow does not reach — a busy
+* camera hits 200 clips or 512 MB first. Every prune logs which bound fired
+* (`reason: age | count | bytes`), so "my 30 days did nothing" has an answer in
+* the log instead of a theory.
+*
 * A file nobody prunes is a disk that fills, and the pruner is the only thing
 * standing between a permanent prebuffer and that.
 *
@@ -88930,8 +90097,12 @@ function clipStem(clipId) {
 * deleted — this repo has twice shipped a green test because the fake supplied
 * what production forgot, and a promise is not a file.
 */
-/** The directory under the addon's data dir. Ours, and only ours. */
-var CLIP_DIR_NAME = "hksv-clips";
+/** An `errno` code off an unknown throw, without a cast. */
+function errnoCode(err) {
+	if (typeof err !== "object" || err === null || !("code" in err)) return null;
+	const { code } = err;
+	return typeof code === "string" ? code : null;
+}
 /** See the class docblock for what each number is, and where it comes from. */
 var DEFAULT_CLIP_BOUNDS = {
 	maxClipBytes: 256 * 1024 * 1024,
@@ -88955,6 +90126,11 @@ var HksvClipStore = class {
 		};
 		this.now = input.now ?? Date.now;
 	}
+	/** This camera's retention. One authority, asked at every prune. */
+	maxAgeMsFor(deviceId) {
+		const resolved = this.input.maxAgeMsFor?.(deviceId);
+		return resolved === void 0 || !Number.isFinite(resolved) || resolved <= 0 ? this.bounds.maxAgeMs : resolved;
+	}
 	/** The per-clip ceiling the tee enforces while writing. */
 	get maxClipBytes() {
 		return this.bounds.maxClipBytes;
@@ -88967,19 +90143,21 @@ var HksvClipStore = class {
 	async open(input) {
 		const clipId = clipIdFor(input.deviceId, input.startedAtMs, input.streamId);
 		const names = clipFileNames(clipId);
-		const dir = this.deviceDir(input.deviceId);
 		const tags = { deviceId: input.deviceId };
+		const root = await this.resolveRootOrWarn(tags);
+		if (root === null) return null;
+		const dir = this.deviceDir(root, input.deviceId);
 		try {
 			await mkdir(dir, { recursive: true });
 			const sink = await createFileSink(join(dir, names.clip));
 			this.inFlight.set(clipId, {
 				deviceId: input.deviceId,
-				stem: stemOf(names.clip)
+				stem: stemOf$1(names.clip)
 			});
 			return {
 				clipId,
 				sink,
-				complete: (outcome) => this.complete(clipId, input, names, outcome)
+				complete: (outcome) => this.complete(clipId, input, names, outcome, root)
 			};
 		} catch (err) {
 			this.inFlight.delete(clipId);
@@ -88995,12 +90173,52 @@ var HksvClipStore = class {
 	}
 	/** Every sidecar for a camera, newest first. What a later provider lists. */
 	async listRecords(deviceId) {
-		const dir = this.deviceDir(deviceId);
+		const catalog = await this.listCatalog(deviceId);
+		return catalog.kind === "catalog" ? catalog.records : [];
+	}
+	/**
+	* ONE directory read, answering the three questions a provider has to tell
+	* apart: what was written, what is still THERE, and — when neither — whether
+	* the location is gone or the read failed.
+	*
+	* `listRecords` is this method's `records` and nothing else, so the published
+	* D550 contract and the provider can never disagree about what the store
+	* holds. The file name set is here rather than a `stat` per clip because the
+	* `readdir` has already answered it: a sidecar whose fMP4 was removed is a
+	* row that must still LIST, saying it cannot be played (D549's `playable`),
+	* and N syscalls to re-learn what one call said is the shape D447 charges
+	* for.
+	*
+	* A device directory that does not exist is an EMPTY catalog, not a refusal:
+	* the location is fine and this camera has recorded nothing. A `readdir` that
+	* failed for any other reason is `failed` — a measurement that failed is
+	* never folded into "no clips" (D393).
+	*/
+	async listCatalog(deviceId) {
+		let root;
+		try {
+			root = await this.input.resolveRoot();
+		} catch (err) {
+			return {
+				kind: "failed",
+				error: err instanceof Error ? err.message : String(err)
+			};
+		}
+		if (root === null) return { kind: "no-root" };
+		const dir = this.deviceDir(root, deviceId);
 		let names;
 		try {
 			names = await readdir(dir);
-		} catch {
-			return [];
+		} catch (err) {
+			if (errnoCode(err) === "ENOENT") return {
+				kind: "catalog",
+				records: [],
+				files: /* @__PURE__ */ new Set()
+			};
+			return {
+				kind: "failed",
+				error: err instanceof Error ? err.message : String(err)
+			};
 		}
 		const records = [];
 		for (const name of names) {
@@ -89008,11 +90226,30 @@ var HksvClipStore = class {
 			const record = await this.readRecord(join(dir, name), deviceId);
 			if (record !== null) records.push(record);
 		}
-		return records.sort((a, b) => b.startedAtMs - a.startedAtMs);
+		return {
+			kind: "catalog",
+			records: records.toSorted((a, b) => b.startedAtMs - a.startedAtMs),
+			files: new Set(names)
+		};
+	}
+	/**
+	* Where ONE artifact of a clip lives, or `null` when there is no root.
+	*
+	* The stem, never a path: the caller (a data-plane route) has a URL segment
+	* and the store owns the layout. Nothing else may compose a path into the
+	* clips location.
+	*/
+	async artifactPath(deviceId, stem, kind) {
+		const root = await this.rootOrNull();
+		if (root === null) return null;
+		const names = clipFileNamesForStem(stem);
+		return join(this.deviceDir(root, deviceId), names[kind]);
 	}
 	/** iOS sent `ack`: HomeKit itself kept this clip. Recorded on the sidecar. */
 	async acknowledge(deviceId, clipId) {
-		const path = join(this.deviceDir(deviceId), clipFileNames(clipId).record);
+		const root = await this.rootOrNull();
+		if (root === null) return;
+		const path = join(this.deviceDir(root, deviceId), clipFileNames(clipId).record);
 		const record = await this.readRecord(path, deviceId);
 		if (record === null) return;
 		await this.writeRecord(path, {
@@ -89020,12 +90257,41 @@ var HksvClipStore = class {
 			acknowledgedByHomeKit: true
 		});
 	}
-	deviceDir(deviceId) {
-		return join(this.input.rootDir, String(deviceId));
+	/**
+	* The root, or `null` with ONE warn. Never throws: the caller's correct move
+	* for every refusal is identical — no clip, HomeKit untouched.
+	*/
+	async resolveRootOrWarn(tags) {
+		try {
+			const root = await this.input.resolveRoot();
+			if (root !== null) return root;
+		} catch (err) {
+			this.log.warn("hksv clip store: resolving the clips location FAILED — nothing is teed", {
+				tags,
+				meta: { error: err instanceof Error ? err.message : String(err) }
+			});
+			return null;
+		}
+		this.log.warn("hksv clip store: no writable clips location — this camera keeps no HomeKit clips", {
+			tags,
+			meta: {}
+		});
+		return null;
+	}
+	/** The root for a READ. Quiet: a read with no location is simply empty. */
+	async rootOrNull() {
+		try {
+			return await this.input.resolveRoot();
+		} catch {
+			return null;
+		}
+	}
+	deviceDir(root, deviceId) {
+		return join(root, String(deviceId));
 	}
-	async complete(clipId, input, names, outcome) {
+	async complete(clipId, input, names, outcome, root) {
 		this.inFlight.delete(clipId);
-		const dir = this.deviceDir(input.deviceId);
+		const dir = this.deviceDir(root, input.deviceId);
 		const tags = { deviceId: input.deviceId };
 		const clipPath = join(dir, names.clip);
 		if (!outcome.sawInit || outcome.bytes === 0) {
@@ -89041,6 +90307,7 @@ var HksvClipStore = class {
 			});
 			return null;
 		}
+		const remux = await this.remuxAndVouch(clipPath, tags, clipId);
 		const thumbnail = await this.mintAndVouch({
 			deviceId: input.deviceId,
 			clipPath,
@@ -89055,17 +90322,19 @@ var HksvClipStore = class {
 			streamId: input.streamId,
 			startedAtMs: outcome.startedAtMs,
 			endedAtMs: outcome.endedAtMs,
-			durationMs: Math.max(0, outcome.endedAtMs - outcome.startedAtMs),
+			durationMs: remux.ok && remux.durationMs !== void 0 ? remux.durationMs : Math.max(0, outcome.endedAtMs - outcome.startedAtMs),
 			prebufferSpanMs: input.prebufferSpanMs,
-			bytes: outcome.bytes,
+			bytes: remux.ok ? remux.bytes : outcome.bytes,
 			fragments: outcome.fragments,
 			file: names.clip,
 			...thumbnail.ok ? { thumbnailFile: names.thumbnail } : { thumbnailUnavailable: { reason: thumbnail.reason } },
+			...remux.ok ? { seekable: true } : { remuxUnavailable: { reason: remux.reason } },
 			...outcome.truncated === null ? {} : { truncated: outcome.truncated },
 			acknowledgedByHomeKit: false,
 			width: input.width,
 			height: input.height,
-			fragmentMs: input.fragmentMs
+			fragmentMs: input.fragmentMs,
+			...input.profile === void 0 ? {} : { profile: input.profile }
 		};
 		await this.writeRecord(join(dir, names.record), record);
 		this.log.info("hksv clip tee: a HomeKit clip was KEPT", {
@@ -89082,13 +90351,53 @@ var HksvClipStore = class {
 				thumbnailUnavailable: record.thumbnailUnavailable?.reason ?? null
 			}
 		});
-		await this.prune(input.deviceId);
+		await this.prune(root, input.deviceId);
 		return record;
 	}
 	/**
 	* Mint, then CHECK. The minter's own verdict decides nothing on its own: a
 	* JPEG is vouched by `stat`, never by a return value.
 	*/
+	/**
+	* Run the faststart pass, and never let it cost the clip.
+	*
+	* The remuxer already vouches for its own output and never throws by
+	* contract — this wrapper exists for the one case a contract cannot cover: a
+	* remuxer that throws anyway. A clip that does not seek is a clip; a clip
+	* this pass ate is a HomeKit recording the operator lost, and that asymmetry
+	* is the whole reason the failure is caught here and named on the record.
+	*/
+	async remuxAndVouch(clipPath, tags, clipId) {
+		const remux = this.input.remuxClip;
+		if (remux === void 0) return {
+			ok: false,
+			reason: "not-attempted"
+		};
+		let result;
+		try {
+			result = await remux({ clipPath });
+		} catch (err) {
+			result = {
+				ok: false,
+				reason: "remux-failed"
+			};
+			this.log.warn("hksv clip tee: the faststart remuxer THREW — the clip is kept unseekable", {
+				tags,
+				meta: {
+					clipId,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
+		}
+		if (!result.ok && result.reason !== "not-attempted") this.log.warn("hksv clip tee: the clip could not be made SEEKABLE — it plays, but nothing can scrub or Range it", {
+			tags,
+			meta: {
+				clipId,
+				reason: result.reason
+			}
+		});
+		return result;
+	}
 	async mintAndVouch(mint) {
 		const { deviceId, jpegPath } = mint;
 		const minter = this.input.mintThumbnail;
@@ -89129,26 +90438,31 @@ var HksvClipStore = class {
 	* sidecars, so a stem whose sidecar never landed — a crash mid-write — is
 	* seen and removed instead of occupying the disk invisibly forever.
 	*/
-	async prune(deviceId) {
-		const cutoff = this.now() - this.bounds.maxAgeMs;
-		const perDevice = await this.scanDevice(deviceId);
-		await this.enforce(perDevice, cutoff, this.bounds.maxClipsPerDevice, this.bounds.maxBytesPerDevice);
+	async prune(root, deviceId) {
+		const perDevice = await this.scanDevice(root, deviceId);
+		await this.enforce(perDevice, this.bounds.maxClipsPerDevice, this.bounds.maxBytesPerDevice);
 		let deviceIds;
 		try {
-			deviceIds = (await readdir(this.input.rootDir, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => Number.parseInt(e.name, 10)).filter((id) => Number.isFinite(id));
+			deviceIds = (await readdir(root, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => Number.parseInt(e.name, 10)).filter((id) => Number.isFinite(id));
 		} catch {
 			return;
 		}
 		const all = [];
-		for (const id of deviceIds) all.push(...await this.scanDevice(id));
-		await this.enforce(all, cutoff, Number.POSITIVE_INFINITY, this.bounds.maxStoreBytes);
+		for (const id of deviceIds) all.push(...await this.scanDevice(root, id));
+		await this.enforce(all, Number.POSITIVE_INFINITY, this.bounds.maxStoreBytes);
 	}
-	async enforce(clips, ageCutoff, maxCount, maxBytes) {
+	/**
+	* Enforce the bounds, oldest first. The AGE is asked per clip's CAMERA — two
+	* cameras with different retentions share this pass, and folding them into
+	* one cutoff would silently give every camera the shortest.
+	*/
+	async enforce(clips, maxCount, maxBytes) {
+		const now = this.now();
 		const ordered = [...clips].sort((a, b) => b.startedAtMs - a.startedAtMs);
 		let kept = 0;
 		let bytes = 0;
 		for (const clip of ordered) {
-			const tooOld = clip.startedAtMs < ageCutoff;
+			const tooOld = clip.startedAtMs < now - this.maxAgeMsFor(clip.deviceId);
 			const overCount = kept >= maxCount;
 			const overBytes = bytes + clip.bytes > maxBytes;
 			if (!tooOld && !overCount && !overBytes) {
@@ -89175,8 +90489,8 @@ var HksvClipStore = class {
 			}
 		});
 	}
-	async scanDevice(deviceId) {
-		const dir = this.deviceDir(deviceId);
+	async scanDevice(root, deviceId) {
+		const dir = this.deviceDir(root, deviceId);
 		let names;
 		try {
 			names = await readdir(dir);
@@ -89186,7 +90500,7 @@ var HksvClipStore = class {
 		const clips = [];
 		for (const name of names) {
 			if (!name.endsWith(".mp4")) continue;
-			const stem = stemOf(name);
+			const stem = stemOf$1(name);
 			if (this.isInFlight(deviceId, stem)) continue;
 			const bytes = await fileSize(join(dir, name));
 			const record = await this.readRecord(join(dir, `${stem}.json`), deviceId);
@@ -89222,7 +90536,19 @@ var HksvClipStore = class {
 		} catch {
 			return null;
 		}
-		const parsed = HksvClipRecordSchema.safeParse(JSON.parse(raw));
+		let parsed;
+		try {
+			parsed = HksvClipRecordSchema.safeParse(JSON.parse(raw));
+		} catch (err) {
+			this.log.warn("hksv clip store: a sidecar is not readable JSON — the clip is not listed", {
+				tags: { deviceId },
+				meta: {
+					path,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
+			return null;
+		}
 		if (parsed.success) return parsed.data;
 		this.log.warn("hksv clip store: a sidecar could not be read — the clip is not listed", {
 			tags: { deviceId },
@@ -89233,11 +90559,22 @@ var HksvClipStore = class {
 		});
 		return null;
 	}
+	/**
+	* ATOMICALLY: a temp file plus a rename, never a `writeFile` in place.
+	*
+	* The sidecar is the only thing that says a clip exists, and it is read
+	* concurrently — by the pruner, and later by whatever lists these clips. A
+	* plain write is visible half-finished, and a half-finished sidecar reads as
+	* a corrupt clip rather than a clip being written. `rename` within one
+	* directory is atomic, so a reader sees the old record or the new one.
+	*/
 	async writeRecord(path, record) {
-		await writeFile(path, JSON.stringify(record, null, 2), "utf8");
+		const staging = `${path}.tmp`;
+		await writeFile(staging, JSON.stringify(record, null, 2), "utf8");
+		await rename(staging, path);
 	}
 };
-function stemOf(fileName) {
+function stemOf$1(fileName) {
 	return fileName.replace(/\.[^.]+$/, "");
 }
 async function fileSize(path) {
@@ -89266,6 +90603,8 @@ async function createFileSink(path) {
 		}
 	};
 }
+/** A decode that has not finished by here is not going to. */
+var CLIP_THUMBNAIL_TIMEOUT_MS = 1e4;
 function buildClipThumbnailArgs(input) {
 	return [
 		"-hide_banner",
@@ -89320,59 +90659,583 @@ function createClipThumbnailMinter(input) {
 		return { ok: true };
 	};
 }
-/**
-* The production runner: one bounded ffmpeg, killed at the deadline.
-*
-* Bounded and killed, not merely awaited — an ffmpeg that never exits on a
-* clip it cannot parse would otherwise hold a process per clip on a hub that
-* already runs a permanent prebuffer per recorded camera.
-*/
-function createFfmpegClipThumbnailRunner(input) {
-	const timeoutMs = input.timeoutMs ?? 1e4;
-	return (args) => new Promise((resolve) => {
-		let settled = false;
-		const finish = (run) => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timer);
-			resolve(run);
+//#endregion
+//#region src/hksv/videoclips-plane.ts
+/**
+* The two data-plane routes behind the HomeKit clip source.
+*
+* Both are hosted by `ctx.dataPlane.serve({ access: 'authenticated' })`, so the
+* hub authenticates and reverse-proxies and this addon produces the bytes.
+* **Neither puts a token in its URL**: the hub's `/addon/<id>/<prefix>` proxy
+* reads the credential from `authorization` OR the session cookie, exactly as
+* the recorder's own playback plane does, so a clip URL may sit in history, in
+* a `Referer` or in a shared log and open nothing (D549 22).
+*
+* ## Why the bytes are served HERE
+*
+* The clips were written by this process, to a `local-path` storage location,
+* and this addon is `hub-only`. A byte path that went anywhere else would be a
+* cross-addon media move — D9/D18, and the repo's one existing such move is
+* capped at 50 MiB with a docblock naming the OOM it caused. `createReadStream
+* ().pipe(res)` gives backpressure natively, which is why the data plane hands
+* an addon the REAL `res` (D447: a raw HTTP stream reads no chunk the socket
+* has not taken).
+*
+* ## What the media route does NOT do
+*
+* It does not remux. A teed clip is `ftyp` + an EMPTY `moov` + `moof`/`mdat`
+* fragments, cut wherever iOS stopped pulling, so the container carries no
+* duration and no index — measured on a byte-identical file
+* (`-movflags +frag_keyframe+empty_moov+default_base_moof`, the tee's own
+* argv): `mvhd.duration = 0`, `mdhd.duration = 0`, no `sidx`, and no `mfra`
+* because nothing wrote a trailer. It decodes end to end, and the row's
+* `timeRange` carries the real duration from the sidecar, but a player cannot
+* map a time to a byte offset from this file. What it would cost to change is
+* measured and written down in D571 rather than guessed at here.
+*
+* ## The thumbnail route has no mint
+*
+* It only ever serves a JPEG the store already stat'd — a still is VOUCHED at
+* write time or it does not exist, and nothing re-mints a teed clip. So a miss
+* is a plain 404, not the 204-with-a-reason contract a live camera needs.
+*/
+/** URL namespaces under `/addon/export-hap/`. */
+var HKSV_CLIP_MEDIA_PREFIX = "hksv-clip";
+var HKSV_CLIP_THUMB_PREFIX = "hksv-clip-thumb";
+/** A stem is what `clipStem` mints: nothing else may reach the filesystem. */
+var MEDIA_PATH = /^\/(\d{1,12})\/([A-Za-z0-9_-]{1,128})\.mp4$/;
+var THUMB_PATH = /^\/(\d{1,12})\/([A-Za-z0-9_-]{1,128})\.jpg$/;
+/** `bytes=a-b` / `bytes=a-` / `bytes=-n`. `'unsatisfiable'` is a 416 rather
+*  than a silently empty 206. */
+function parseRange(header, size) {
+	if (header === void 0) return null;
+	const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+	if (match === null) return null;
+	const [, rawStart, rawEnd] = match;
+	if (rawStart === "" && rawEnd === "") return "unsatisfiable";
+	if (rawStart === "") {
+		const length = Number(rawEnd);
+		if (length <= 0) return "unsatisfiable";
+		return {
+			start: Math.max(0, size - length),
+			end: size - 1
 		};
-		const child = input.spawnFn(input.ffmpegBinaryPath, [...args], { stdio: [
-			"ignore",
-			"ignore",
-			"pipe"
-		] });
-		let stderr = "";
-		child.stderr?.on("data", (chunk) => {
-			if (stderr.length < 2e3) stderr += chunk.toString("utf8");
-		});
-		const timer = setTimeout(() => {
-			child.kill("SIGKILL");
-			finish({
-				code: null,
-				timedOut: true,
-				spawnFailed: false,
-				stderr
+	}
+	const start = Number(rawStart);
+	if (start >= size) return "unsatisfiable";
+	const end = rawEnd === "" ? size - 1 : Math.min(Number(rawEnd), size - 1);
+	if (end < start) return "unsatisfiable";
+	return {
+		start,
+		end
+	};
+}
+function pathnameOf(req) {
+	const raw = req.url ?? "/";
+	const query = raw.indexOf("?");
+	return query === -1 ? raw : raw.slice(0, query);
+}
+function address(req, pattern) {
+	const match = pattern.exec(pathnameOf(req));
+	if (match === null) return null;
+	const deviceId = Number(match[1]);
+	const stem = match[2];
+	if (!Number.isInteger(deviceId) || stem === void 0) return null;
+	return {
+		deviceId,
+		stem
+	};
+}
+function createHksvClipPlanes(deps) {
+	/**
+	* The path of one artifact, or `null` with a reason ALREADY logged.
+	*
+	* A 404 is work this route dropped, and silence reads as "never happened" —
+	* so every miss is one warn carrying `tags: { deviceId }`, which is the only
+	* key a "why is 617 missing its clips and 615 not?" question can be answered
+	* by.
+	*/
+	async function locate(addressed, artifact) {
+		const { deviceId, stem } = addressed;
+		let path;
+		try {
+			path = await deps.artifactPath(deviceId, stem, artifact);
+		} catch (err) {
+			deps.logger.warn("videoclips: could not resolve a HomeKit clip artifact", {
+				tags: { deviceId },
+				meta: {
+					stem,
+					artifact,
+					error: err instanceof Error ? err.message : String(err)
+				}
 			});
-		}, timeoutMs);
-		timer.unref?.();
-		child.on("error", (err) => {
-			finish({
-				code: null,
-				timedOut: false,
-				spawnFailed: true,
-				stderr: err.message
+			return null;
+		}
+		if (path === null) {
+			deps.logger.warn("videoclips: no writable HomeKit clips location — nothing to serve", {
+				tags: { deviceId },
+				meta: {
+					stem,
+					artifact
+				}
 			});
-		});
-		child.on("close", (code) => {
-			finish({
-				code,
-				timedOut: false,
-				spawnFailed: false,
-				stderr
+			return null;
+		}
+		try {
+			const stats = await stat(path);
+			if (!stats.isFile()) throw new Error("not a file");
+			return {
+				path,
+				size: stats.size
+			};
+		} catch (err) {
+			deps.logger.warn("videoclips: a HomeKit clip artifact was asked for and is not there", {
+				tags: { deviceId },
+				meta: {
+					stem,
+					artifact,
+					error: err instanceof Error ? err.message : String(err)
+				}
 			});
+			return null;
+		}
+	}
+	function readOnly(req, res) {
+		if (req.method === "GET" || req.method === "HEAD") return true;
+		res.writeHead(405, { allow: "GET, HEAD" });
+		res.end();
+		return false;
+	}
+	const mediaHandler = async (req, res) => {
+		if (!readOnly(req, res)) return;
+		const addressed = address(req, MEDIA_PATH);
+		if (addressed === null) {
+			res.writeHead(400);
+			res.end();
+			return;
+		}
+		const found = await locate(addressed, "clip");
+		if (found === null) {
+			res.writeHead(404);
+			res.end();
+			return;
+		}
+		const base = {
+			"content-type": "video/mp4",
+			"accept-ranges": "bytes",
+			"cache-control": "private, max-age=0, must-revalidate"
+		};
+		const range = parseRange(req.headers.range, found.size);
+		if (range === "unsatisfiable") {
+			res.writeHead(416, {
+				...base,
+				"content-range": `bytes */${String(found.size)}`
+			});
+			res.end();
+			return;
+		}
+		if (range === null) {
+			res.writeHead(200, {
+				...base,
+				"content-length": String(found.size)
+			});
+			if (req.method === "HEAD") {
+				res.end();
+				return;
+			}
+			createReadStream(found.path).pipe(res);
+			return;
+		}
+		res.writeHead(206, {
+			...base,
+			"content-range": `bytes ${String(range.start)}-${String(range.end)}/${String(found.size)}`,
+			"content-length": String(range.end - range.start + 1)
 		});
-	});
+		if (req.method === "HEAD") {
+			res.end();
+			return;
+		}
+		createReadStream(found.path, {
+			start: range.start,
+			end: range.end
+		}).pipe(res);
+	};
+	const thumbHandler = async (req, res) => {
+		if (!readOnly(req, res)) return;
+		const addressed = address(req, THUMB_PATH);
+		if (addressed === null) {
+			res.writeHead(400);
+			res.end();
+			return;
+		}
+		const found = await locate(addressed, "thumbnail");
+		if (found === null) {
+			res.writeHead(404);
+			res.end();
+			return;
+		}
+		res.writeHead(200, {
+			"content-type": "image/jpeg",
+			"content-length": String(found.size),
+			"cache-control": "private, max-age=31536000, immutable"
+		});
+		if (req.method === "HEAD") {
+			res.end();
+			return;
+		}
+		createReadStream(found.path).pipe(res);
+	};
+	return {
+		mediaPrefix: HKSV_CLIP_MEDIA_PREFIX,
+		thumbPrefix: HKSV_CLIP_THUMB_PREFIX,
+		mediaHandler,
+		thumbHandler
+	};
+}
+//#endregion
+//#region src/hksv/videoclips-source.ts
+/**
+* The `videoclips` SOURCE over the clips this addon teed to HomeKit.
+*
+* ## Where it runs, and why there is no hand-off
+*
+* `export-hap` is `placement: 'hub-only'` and the teed clips live on a
+* `local-path` storage location this process writes with `node:fs`. D550
+* recorded the open question as "the store lives in the hub-only `export-hap`
+* runner, so listing and serving must REACH it from wherever the provider
+* mounts". The answer is that the provider mounts HERE: `videoclips` is a
+* `scope:'device'` + `mode:'collection'` wrapper, so every addon that declares
+* it becomes one of the camera's bindings (`collectionBindings`, gated only by
+* the cap's `deviceTypes`), and `resolveWrapperNodeId` routes a wrapper to the
+* hub — which is where this addon already is. Nothing about a `videoclips`
+* provider requires owning the device.
+*
+* That removes the hand-off rather than building one, and it is the only shape
+* that obeys both rules D550 named: addons never import each other (this one
+* imports nothing — it reads its own store), and frames never cross a process
+* boundary (the bytes never enter a cap call at all; `getClipPlayback` answers
+* a URL into this addon's own data plane and the file is streamed with `Range`
+* from the disk it was written to). The rejected alternative was to register
+* the provider in the recorder and have it fetch clips over `ctx.api` — a
+* cross-addon byte move by handle at best, and the repo's one existing such
+* move carries a 50 MiB cap and a docblock naming the OOM it caused.
+*
+* ## The source EXISTS because of HomeKit, and is not a switch
+*
+* A camera has this source because it is exported to HomeKit AND HomeKit
+* recording is on for it; turn either off and the row is gone (D550, D569 § 5).
+* There is deliberately no enable control of its own — a knob over somebody
+* else's decision is D62's defect. `keepClips` is NOT that gate either: it
+* governs the TEE, and the clips already kept remain the truth about this
+* camera, so the row stays and its `reason` says the copies are off.
+*
+* ## `ok` is measured, and an empty list is not always an answer
+*
+* D561: `ok` may never be a default. Here the measurement is a real read of the
+* clips directory, and every answer this source gives — the source row and the
+* clip list — comes from ONE such read. The states are the existing five, and
+* no sixth was needed:
+*
+*  - `ok` — the directory answered. Including with nothing: a camera that has
+*    recorded no HomeKit clip yet is a complete list of zero, and the `reason`
+*    says which flavour of nothing it is.
+*  - `no-storage` — there is no writable `homekitClips` location: none seeded,
+*    or it is `readonly` / `drain` / `disabled` (D385, named by
+*    `clip-location.ts`, which is the only module that may interpret the mode).
+*    Exactly the Reolink meaning: the medium is not there.
+*  - `unreachable` — the storage cap could not be reached, or the directory
+*    read threw. A measurement that failed is never folded into "no clips"
+*    (D393).
+*  - `index-empty` — HomeKit recording is switched ON for this camera and the
+*    store holds nothing, because `buildHksvRecording` WITHHELD the
+*    advertisement (no H.264 slot ≤ 1080p, a GOP longer than any fragment
+*    length, or unreadable profiles). The camera's own switch disagrees with
+*    its own index, which is what this state means on the Reolink surface too,
+*    and the refusal travels verbatim in `reason`.
+*  - `sleeping` — never. There is no camera to wake: the read is a local
+*    directory read.
+*/
+/** What the picker calls this source. */
+var HKSV_CLIP_SOURCE_LABEL = "HomeKit clips";
+/** Why a listed row has no bytes behind it. Verbatim on `unplayableReason`. */
+var CLIP_FILE_MISSING = "clip-file-missing";
+function createHksvVideoclipsProvider(deps) {
+	const now = deps.now ?? Date.now;
+	/**
+	* The one read, and the state it proves.
+	*
+	* `null` means this camera has no HomeKit clip source at all — it is not
+	* exported, or HomeKit recording is off for it. Not an availability: a row
+	* that should not exist is not a row saying it is unhappy.
+	*/
+	async function measure(deviceId) {
+		const facts = deps.describeCamera(deviceId);
+		if (!facts.exported || !facts.recording) return null;
+		const catalog = await deps.readCatalog(deviceId);
+		return {
+			availability: availabilityFor(facts, catalog),
+			catalog
+		};
+	}
+	function availabilityFor(facts, catalog) {
+		if (catalog.kind === "failed") return {
+			state: "unreachable",
+			reason: `the HomeKit clips location could not be read: ${catalog.error}`
+		};
+		if (catalog.kind === "no-root") {
+			const refusal = deps.locationRefusal();
+			if (refusal === "unreachable") return {
+				state: "unreachable",
+				reason: "the storage capability could not be reached (unreachable)"
+			};
+			return {
+				state: "no-storage",
+				reason: refusal === "not-writable" ? "the HomeKit clips location is not writable (not-writable) — readonly, draining or disabled" : "no HomeKit clips location exists yet (no-location)"
+			};
+		}
+		const asOf = now();
+		if (catalog.records.length > 0) return {
+			state: "ok",
+			catalogAsOf: asOf,
+			...facts.keepingClips ? {} : { reason: "copies are switched off for this camera — nothing new is being kept" }
+		};
+		const withheld = facts.lastBuild?.withheld;
+		if (withheld !== void 0 && withheld !== null) {
+			const detail = facts.lastBuild?.detail;
+			return {
+				state: "index-empty",
+				catalogAsOf: asOf,
+				reason: `HomeKit recording is switched on for this camera but the advertisement was WITHHELD (${withheld})` + (detail === null || detail === void 0 ? "" : `: ${detail}`) + " — HomeKit has never recorded it, so there is nothing to keep"
+			};
+		}
+		return {
+			state: "ok",
+			catalogAsOf: asOf,
+			reason: facts.keepingClips ? "nothing has been recorded by HomeKit for this camera yet" : "copies are switched off for this camera — nothing new is being kept, and nothing was"
+		};
+	}
+	function toClip(deviceId, record, files) {
+		const names = clipFileNames(record.clipId);
+		const hasBytes = files.has(record.file);
+		const vouchedThumb = record.thumbnailFile !== void 0 && files.has(record.thumbnailFile) ? deps.thumbnailUrl(deviceId, stemOf(names.thumbnail)) : null;
+		return {
+			id: record.clipId,
+			source: HKSV_CLIP_SOURCE,
+			kind: "native",
+			timeRange: {
+				startMs: record.startedAtMs,
+				endMs: record.endedAtMs
+			},
+			...vouchedThumb === null ? { thumbnailUnavailable: { reason: thumbnailRefusal(record, files) } } : { thumbnail: vouchedThumb },
+			...hasBytes ? {} : {
+				playable: false,
+				unplayableReason: CLIP_FILE_MISSING
+			}
+		};
+	}
+	/**
+	* The store's five reasons, narrowed onto the cap's four.
+	*
+	* The narrowing is LOSSY and it is forced: `ClipSchema.thumbnailUnavailable`
+	* is a closed enum that `ui-library` maps exhaustively, so widening it is a
+	* breaking change to a consumer, and this source's reasons postdate it. The
+	* lossless copy is not lost — it is on the sidecar and on the listing line —
+	* and the split preserves the only distinction a surface can act on:
+	*
+	*  - `no-keyframe` — the CLIP had nothing decodable at the trigger instant
+	*    (`no-init-segment`, `decode-failed`, `timed-out`).
+	*  - `unsupported` — no still exists and nothing here will make one
+	*    (`ffmpeg-missing`, `not-attempted`, or a JPEG that is no longer on
+	*    disk). Nothing re-mints a teed clip, so every one of these is final.
+	*/
+	function thumbnailRefusal(record, files) {
+		if (record.thumbnailFile !== void 0 && !files.has(record.thumbnailFile)) return "unsupported";
+		const reason = record.thumbnailUnavailable?.reason;
+		if (reason === "no-init-segment" || reason === "decode-failed" || reason === "timed-out") return "no-keyframe";
+		return "unsupported";
+	}
+	return {
+		listSources: async ({ deviceId }) => {
+			const measured = await measure(deviceId);
+			if (measured === null) return [];
+			deps.logger.info("videoclips: measured the HomeKit clip source", {
+				tags: { deviceId },
+				meta: {
+					source: HKSV_CLIP_SOURCE,
+					state: measured.availability.state,
+					reason: measured.availability.reason ?? null,
+					clips: measured.catalog.kind === "catalog" ? measured.catalog.records.length : null
+				}
+			});
+			return [{
+				source: HKSV_CLIP_SOURCE,
+				addonId: deps.addonId,
+				label: HKSV_CLIP_SOURCE_LABEL,
+				availability: measured.availability
+			}];
+		},
+		listClips: async ({ deviceId, since, until, limit }) => {
+			const measured = await measure(deviceId);
+			if (measured === null) return [];
+			const tags = { deviceId };
+			const catalog = measured.catalog;
+			const records = catalog.kind === "catalog" ? catalog.records : [];
+			const files = catalog.kind === "catalog" ? catalog.files : /* @__PURE__ */ new Set();
+			const ordered = records.filter((r) => r.startedAtMs <= until && r.endedAtMs >= since).toSorted((a, b) => b.startedAtMs - a.startedAtMs);
+			const capped = limit === void 0 ? ordered : ordered.slice(0, limit);
+			const clips = capped.map((record) => toClip(deviceId, record, files));
+			const unplayable = clips.filter((c) => c.playable === false).length;
+			const vouched = clips.filter((c) => c.thumbnail !== void 0).length;
+			deps.logger.info("videoclips: listed the HomeKit clips", {
+				tags,
+				meta: {
+					source: HKSV_CLIP_SOURCE,
+					clips: clips.length,
+					truncated: limit !== void 0 && ordered.length > limit,
+					unplayable,
+					thumbsVouched: vouched,
+					thumbsUnavailable: clips.length - vouched,
+					thumbnailReason: capped.find((r) => r.thumbnailFile === void 0)?.thumbnailUnavailable?.reason,
+					state: measured.availability.state
+				}
+			});
+			if (clips.length === 0 && measured.availability.state !== "ok") {
+				deps.logger.warn("videoclips: nothing to list, and the HomeKit clip source cannot answer", {
+					tags,
+					meta: {
+						branch: "refused-empty",
+						state: measured.availability.state,
+						reason: measured.availability.reason ?? null
+					}
+				});
+				throw new Error(`videoclips: device ${String(deviceId)} listed no HomeKit clips, and that is not an empty window — the source is "${measured.availability.state}"` + (measured.availability.reason === void 0 ? "." : `: ${measured.availability.reason}`));
+			}
+			return clips;
+		},
+		getClipPlayback: async ({ deviceId, clipId, profile }) => {
+			const record = await findRecord(deviceId, clipId);
+			if (profile !== void 0) deps.logger.debug("videoclips: a HomeKit clip has one rendition; the profile is moot", {
+				tags: { deviceId },
+				meta: {
+					clipId,
+					profile,
+					width: record.width,
+					height: record.height
+				}
+			});
+			return {
+				playbackUrl: deps.mediaUrl(deviceId, stemOf(clipFileNames(clipId).clip)),
+				format: "mp4",
+				...record.profile === void 0 ? {} : { served: record.profile }
+			};
+		},
+		/**
+		* The clip's BYTES, inline and bounded — the seam another ADDON pulls
+		* (D558), never the path a player takes.
+		*
+		* A browser or a viewer session plays `getClipPlayback`'s URL; an addon
+		* cannot, because `AddonDataPlane` only lets an addon SERVE. So this is the
+		* one place HomeKit clip bytes enter a cap envelope, and the bound is the
+		* cap's own 50 MiB — held whole, base64, in this process AND the caller's,
+		* on a hub that has already been OOM'd once (D9/D18). Above the bound it
+		* REFUSES with the size: half a video is worse than an honest refusal.
+		*
+		* A 256 MB clip (the tee's per-clip rail) is therefore refusable here and
+		* playable through the route, which is stated rather than discovered.
+		*/
+		readClipBytes: async ({ deviceId, clipId, maxBytes }) => {
+			const record = await findRecord(deviceId, clipId);
+			const stem = stemOf(clipFileNames(clipId).clip);
+			if (record.profile === void 0) {
+				deps.logger.warn("videoclips: a HomeKit clip cannot say which profile it recorded from", {
+					tags: { deviceId },
+					meta: {
+						clipId,
+						branch: "no-profile"
+					}
+				});
+				throw new Error(`videoclips: clip "${clipId}" does not record which profile HomeKit recorded from, so the twin it would be served as cannot be named`);
+			}
+			const bound = Math.min(maxBytes ?? 52428800, VIDEOCLIPS_MAX_READ_BYTES);
+			if (record.bytes > bound) throw new Error(`videoclips: clip "${clipId}" is ${String(record.bytes)} bytes, over the ${String(bound)}-byte bound for an inline read — fetch it from its playback URL`);
+			const path = await deps.clipFilePath(deviceId, stem);
+			if (path === null) throw new Error(`videoclips: the HomeKit clips location for device ${String(deviceId)} is not readable`);
+			let bytes;
+			try {
+				bytes = await readFile(path);
+			} catch (err) {
+				deps.logger.warn("videoclips: the fMP4 of a listed HomeKit clip could not be read", {
+					tags: { deviceId },
+					meta: {
+						clipId,
+						branch: CLIP_FILE_MISSING,
+						error: errorText(err)
+					}
+				});
+				throw new Error(`videoclips: clip "${clipId}" has a sidecar but no readable bytes (${CLIP_FILE_MISSING})`, { cause: err });
+			}
+			deps.logger.info("videoclips: served a HomeKit clip inline", {
+				tags: { deviceId },
+				meta: {
+					clipId,
+					bytes: bytes.byteLength,
+					served: record.profile
+				}
+			});
+			return {
+				base64: bytes.toString("base64"),
+				contentType: "video/mp4",
+				name: `${stem}.mp4`,
+				bytes: bytes.byteLength,
+				served: record.profile,
+				...record.durationMs > 0 ? { durationMs: record.durationMs } : {}
+			};
+		}
+	};
+	/**
+	* The catalog row for one clip, or a THROW naming which of the three things
+	* went wrong: not ours, not held, or held with no bytes behind it. Shared by
+	* the two byte paths so they can never disagree about what a clip id means.
+	*/
+	async function findRecord(deviceId, clipId) {
+		if (!clipId.startsWith(`hksv:`)) throw new Error(`videoclips: clip id "${clipId}" was not minted by the HomeKit source`);
+		if (!clipId.startsWith(`hksv:${String(deviceId)}:`)) throw new Error(`videoclips: clip id "${clipId}" belongs to another camera — ids are self-contained and name the device that teed them`);
+		const measured = await measure(deviceId);
+		if (measured === null) throw new Error(`videoclips: device ${String(deviceId)} has no HomeKit clip source — it is not exported to HomeKit, or HomeKit recording is off for it`);
+		const catalog = measured.catalog;
+		if (catalog.kind !== "catalog") throw new Error(`videoclips: the HomeKit clips for device ${String(deviceId)} cannot be read — the source is "${measured.availability.state}"`);
+		const record = catalog.records.find((r) => r.clipId === clipId) ?? null;
+		if (record === null) {
+			deps.logger.warn("videoclips: asked for a HomeKit clip the catalog does not hold", {
+				tags: { deviceId },
+				meta: {
+					clipId,
+					branch: "no-catalog-row"
+				}
+			});
+			throw new Error(`videoclips: no clip "${clipId}" is held for device ${String(deviceId)}`);
+		}
+		if (!catalog.files.has(record.file)) {
+			deps.logger.warn("videoclips: the fMP4 for a listed HomeKit clip is gone", {
+				tags: { deviceId },
+				meta: {
+					clipId,
+					branch: CLIP_FILE_MISSING,
+					file: record.file
+				}
+			});
+			throw new Error(`videoclips: clip "${clipId}" has a sidecar but no bytes (${CLIP_FILE_MISSING})`);
+		}
+		return record;
+	}
+}
+function errorText(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/** `<stem>.mp4` → `<stem>`. The routes address a stem; the store owns the rest. */
+function stemOf(fileName) {
+	const dot = fileName.lastIndexOf(".");
+	return dot === -1 ? fileName : fileName.slice(0, dot);
 }
 //#endregion
 //#region src/mappers/builders/generic/characteristic-update.ts
@@ -104201,7 +106064,8 @@ var ClipTeeRunner = class {
 			prebufferSpanMs: this.request.prebufferSpanMs,
 			width: this.input.width,
 			height: this.input.height,
-			fragmentMs: this.input.fragmentMs
+			fragmentMs: this.input.fragmentMs,
+			...this.input.profile === void 0 ? {} : { profile: this.input.profile }
 		});
 		if (open === null) {
 			this.request.subscription.release();
@@ -105169,9 +107033,26 @@ async function buildHksvRecording(input) {
 	const { bctx } = input;
 	const { ctx, numericDeviceId } = bctx;
 	const log = ctx.logger.withTags({ deviceId: numericDeviceId });
+	/**
+	* Record the verdict for the clip source, next to the log line that already
+	* states it. A camera HomeKit never recorded is not "a camera with no clips",
+	* and `listSources` can only say which it is if the refusal was written down
+	* (D571). Every `return null` below passes through here.
+	*/
+	const note = (withheld, detail) => {
+		const outcome = {
+			deviceId: numericDeviceId,
+			advertised: withheld === null,
+			withheld,
+			detail,
+			atMs: Date.now()
+		};
+		bctx.options.noteHksvOutcome?.(outcome);
+	};
 	const entries = await readProfileEntries(bctx);
 	if (entries === null) {
 		log.warn("export-hap: HKSV withheld — could not read the camera profiles", {});
+		note("profiles-unreadable", "cameraStreams.getProfileRtspEntries could not be read");
 		return null;
 	}
 	const choice = pickRecordingSource(entries);
@@ -105180,6 +107061,7 @@ async function buildHksvRecording(input) {
 			refusal: choice.refusal,
 			reason: refusalReason(choice.refusal)
 		} });
+		note("no-recordable-stream", `${choice.refusal}: ${refusalReason(choice.refusal)}`);
 		return null;
 	}
 	const source = choice.source;
@@ -105190,8 +107072,11 @@ async function buildHksvRecording(input) {
 			gopMs,
 			brokerId: source.brokerId
 		} });
+		note("key-frame-interval", `gopMs=${String(gopMs ?? "unknown")}`);
 		return null;
 	}
+	const parsedProfile = CamProfileSchema.safeParse(source.profile);
+	const recordedProfile = parsedProfile.success ? parsedProfile.data : null;
 	const fps = resolveFps(input.fpsByProfile, source.profile);
 	const options = buildRecordingOptions({
 		width: source.width,
@@ -105199,14 +107084,16 @@ async function buildHksvRecording(input) {
 		fps,
 		fragmentLengthMs
 	});
-	const clipStore = bctx.options.hksvClipStore;
+	const keepClips = bctx.options.hapDeviceSettings.keepHomekitClips !== false;
+	const clipStore = keepClips ? bctx.options.hksvClipStore : null;
 	const openClipTee = clipStore === null ? void 0 : createClipTeeFactory({
 		logger: log,
 		deviceId: numericDeviceId,
 		store: clipStore,
 		width: source.width,
 		height: source.height,
-		fragmentMs: fragmentLengthMs
+		fragmentMs: fragmentLengthMs,
+		...recordedProfile === null ? {} : { profile: recordedProfile }
 	});
 	const delegate = new HksvRecordingDelegate({
 		logger: log,
@@ -105235,8 +107122,10 @@ async function buildHksvRecording(input) {
 		advertisedFps: advertisedResolution?.[2] ?? null,
 		fragmentLengthMs,
 		sourceGopMs: gopMs ?? "unknown",
-		clipsKept: openClipTee !== void 0
+		clipsKept: openClipTee !== void 0,
+		clipsSwitchedOn: keepClips
 	} });
+	note(null, null);
 	return {
 		options,
 		delegate,
@@ -106519,6 +108408,65 @@ function resolveHksvRecording(settings) {
 * negotiation is built we say `streaming-enabled: false`, so declining is the
 * only thing a controller can do with it.
 */
+/**
+* Keep a copy of what we send HomeKit, for this camera.
+*
+* ABSENT MEANS ON, for the same reason as `resolveHksvRecording` and one
+* stronger: HKSV has no read-back, so every recording made while this said
+* "off by accident" is gone permanently. Only an explicit `false` turns it off.
+*/
+function resolveKeepHomekitClips(settings) {
+	return settings?.keepClips !== false;
+}
+/** This addon's id, as the manifest declares it and the registry knows it. */
+var EXPORT_HAP_ADDON_ID = "export-hap";
+/**
+* Whether a camera HAS a HomeKit clip source, read from the authorities that
+* already own each half.
+*
+* The source exists because the camera is EXPORTED to HomeKit and HomeKit
+* RECORDING is on for it, and it goes away when either goes off (D550, D569 §
+* 5). There is no third switch: a knob of this source's own would be a second
+* authority over somebody else's decision (D62), and this function is the only
+* place the two are read together.
+*
+* `keepClips` is deliberately NOT part of existence. It governs the TEE, and
+* the clips already kept are still the truth about this camera — so the row
+* stays and says the copies are off, which is D62's other half: an off switch
+* is REPORTED off, never made to look like a broken camera.
+*/
+function describeHksvCamera(entry, lastBuild) {
+	const isCamera = entry !== null && entry.mapperKind === "camera";
+	return {
+		exported: isCamera,
+		recording: isCamera && resolveHksvRecording(entry.settings),
+		keepingClips: isCamera && resolveKeepHomekitClips(entry.settings),
+		lastBuild
+	};
+}
+/** What ships, and what an unset global resolves to. */
+var DEFAULT_CLIP_RETENTION_DAYS = 14;
+/** The rails on the retention itself. Zero would silently disable the tee. */
+var MIN_CLIP_RETENTION_DAYS = 1;
+var MAX_CLIP_RETENTION_DAYS = 365;
+/**
+* This camera's retention in days: per-device override → global default →
+* {@link DEFAULT_CLIP_RETENTION_DAYS}.
+*
+* The cascade rule the repo already pays for (`stationary-settings.ts`):
+* **reset == unset**. A cleared override and a key that was never written must
+* resolve to the same number, or the Reset button is a lie. A value outside the
+* rails is not stored as a lie either — it falls back rather than turning the
+* tee into a no-op (0 days) or an unbounded archive.
+*/
+function resolveClipRetentionDays(settings, globalDefaultDays) {
+	const fleet = clampRetentionDays(globalDefaultDays) ?? 14;
+	return clampRetentionDays(settings?.clipRetentionDays) ?? fleet;
+}
+function clampRetentionDays(value) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < MIN_CLIP_RETENTION_DAYS) return null;
+	return Math.min(Math.floor(value), MAX_CLIP_RETENTION_DAYS);
+}
 function resolveMultiTierService(settings) {
 	return settings?.multiTierService === true;
 }
@@ -106546,6 +108494,7 @@ var DEFAULT_CONFIG = {
 	fixedPin: "",
 	interfaceName: "",
 	ptzPulseMs: 400,
+	clipRetentionDays: 14,
 	identity: {
 		username: "",
 		pincode: "",
@@ -106618,6 +108567,18 @@ var ExportHapAddon = class extends BaseAddon {
 	* failure to exist is one line at boot and not a surprise mid-recording.
 	*/
 	hksvClipStore = null;
+	/** Resolves the declared `homekitClips` location; the doorbell invalidates it. */
+	hksvClipLocation = null;
+	/**
+	* What `buildHksvRecording` decided per camera, in this process.
+	*
+	* A MIRROR of the build, written by it and read only to be REPORTED: the
+	* clip source's `index-empty` ("the switch says record and the store holds
+	* nothing") is only honest if it can name which refusal fired (D571).
+	*/
+	hksvBuilds = new HksvBuildOutcomes();
+	/** The clip byte + still routes. `null` until `onInitialize` has served them. */
+	hksvClipPlanes = null;
 	/**
 	* THE bridge. Lazily created and published the first time a non-camera
 	* accessory needs it; never torn down while the addon runs, because an
@@ -106644,14 +108605,26 @@ var ExportHapAddon = class extends BaseAddon {
 			this.lastError = errMsg(err);
 			this.ctx.logger.error("export-hap: HAP storage init failed", { meta: { error: this.lastError } });
 		}
+		this.hksvClipLocation = new HksvClipLocation({
+			logger: this.ctx.logger.child("hksv-clips"),
+			ports: createClipLocationPorts(this.ctx.api)
+		});
 		this.hksvClipStore = new HksvClipStore({
 			logger: this.ctx.logger.child("hksv-clips"),
-			rootDir: path.join(this.ctx.dataDir, CLIP_DIR_NAME),
-			mintThumbnail: createClipThumbnailMinter({ runner: createFfmpegClipThumbnailRunner({
+			resolveRoot: () => this.hksvClipLocation?.root() ?? Promise.resolve(null),
+			maxAgeMsFor: (deviceId) => resolveClipRetentionDays(this.findEntry(deviceId)?.settings, this.config.clipRetentionDays) * 24 * 60 * 60 * 1e3,
+			mintThumbnail: createClipThumbnailMinter({ runner: createBoundedFfmpegRunner({
+				ffmpegBinaryPath: "ffmpeg",
+				spawnFn: spawn,
+				timeoutMs: CLIP_THUMBNAIL_TIMEOUT_MS
+			}) }),
+			remuxClip: createClipRemuxer({ runner: createBoundedFfmpegRunner({
 				ffmpegBinaryPath: "ffmpeg",
-				spawnFn: spawn
+				spawnFn: spawn,
+				timeoutMs: CLIP_REMUX_TIMEOUT_MS
 			}) })
 		});
+		await this.serveHksvClipPlanes();
 		const validKinds = new Set(SUPPORTED_MAPPER_KINDS);
 		const cleaned = this.config.exposed.filter((entry) => {
 			if (validKinds.has(entry.mapperKind)) return true;
@@ -106678,36 +108651,51 @@ var ExportHapAddon = class extends BaseAddon {
 		});
 		this.subscribeDeviceProvisionedForReconcile();
 		this.subscribeDeviceReadyForReconcile();
+		this.subscribeStorageLocationsForClips();
 		this.disposeSharedRebuildTimers();
+		const provider = {
+			getStatus: async () => {
+				const anyPaired = Array.from(this.exposed.values()).some((m) => accessoryPaired(m.accessory));
+				const linkState = this.lastError ? "error" : anyPaired ? "linked" : "unlinked";
+				const setup = this.buildSetupBlock();
+				return {
+					linkState,
+					exposedDeviceCount: this.exposed.size,
+					...this.lastError ? { error: this.lastError } : {},
+					...setup ? { setup } : {}
+				};
+			},
+			listSupportedDeviceKinds: async () => [...HAP_EXPORTABLE_DEVICE_TYPES],
+			listExposedDevices: async () => Array.from(this.exposed.entries()).map(([deviceId, m]) => {
+				const entry = this.config.exposed.find((e) => e.deviceId === deviceId);
+				return {
+					deviceId,
+					exposedAs: m.accessory.displayName,
+					...entry?.capabilities ? { capabilities: [...entry.capabilities] } : {}
+				};
+			}),
+			exposeDevice: async ({ deviceId, capabilities }) => this.exposeDevice(deviceId, capabilities),
+			unexposeDevice: async ({ deviceId }) => this.unexposeDevice(deviceId),
+			getDeviceSettingsContribution: (input) => this.buildDeviceSettingsContribution(input.deviceId),
+			getDeviceLiveContribution: async () => null,
+			applyDeviceSettingsPatch: (input) => this.applyDeviceSettingsPatch(input.deviceId, input.patch)
+		};
+		const clipsProvider = createHksvVideoclipsProvider({
+			logger: this.ctx.logger.child("hksv-clips"),
+			addonId: EXPORT_HAP_ADDON_ID,
+			describeCamera: (deviceId) => describeHksvCamera(this.findEntry(deviceId), this.hksvBuilds.lastFor(deviceId)),
+			readCatalog: async (deviceId) => await this.hksvClipStore?.listCatalog(deviceId) ?? { kind: "no-root" },
+			locationRefusal: () => this.hksvClipLocation?.lastRefusal ?? null,
+			mediaUrl: (deviceId, stem) => this.hksvClipUrl("media", deviceId, stem),
+			thumbnailUrl: (deviceId, stem) => this.hksvClipUrl("thumb", deviceId, stem),
+			clipFilePath: async (deviceId, stem) => await this.hksvClipStore?.artifactPath(deviceId, stem, "clip") ?? null
+		});
 		return [{
 			capability: deviceExportCapability,
-			provider: {
-				getStatus: async () => {
-					const anyPaired = Array.from(this.exposed.values()).some((m) => accessoryPaired(m.accessory));
-					const linkState = this.lastError ? "error" : anyPaired ? "linked" : "unlinked";
-					const setup = this.buildSetupBlock();
-					return {
-						linkState,
-						exposedDeviceCount: this.exposed.size,
-						...this.lastError ? { error: this.lastError } : {},
-						...setup ? { setup } : {}
-					};
-				},
-				listSupportedDeviceKinds: async () => [...HAP_EXPORTABLE_DEVICE_TYPES],
-				listExposedDevices: async () => Array.from(this.exposed.entries()).map(([deviceId, m]) => {
-					const entry = this.config.exposed.find((e) => e.deviceId === deviceId);
-					return {
-						deviceId,
-						exposedAs: m.accessory.displayName,
-						...entry?.capabilities ? { capabilities: [...entry.capabilities] } : {}
-					};
-				}),
-				exposeDevice: async ({ deviceId, capabilities }) => this.exposeDevice(deviceId, capabilities),
-				unexposeDevice: async ({ deviceId }) => this.unexposeDevice(deviceId),
-				getDeviceSettingsContribution: (input) => this.buildDeviceSettingsContribution(input.deviceId),
-				getDeviceLiveContribution: async () => null,
-				applyDeviceSettingsPatch: (input) => this.applyDeviceSettingsPatch(input.deviceId, input.patch)
-			}
+			provider
+		}, {
+			capability: videoclipsCapability,
+			provider: clipsProvider
 		}];
 	}
 	async onConfigChanged() {
@@ -106832,6 +108820,7 @@ var ExportHapAddon = class extends BaseAddon {
 		if (next.length !== this.config.exposed.length) await this.updateGlobalSettings({ exposed: next });
 		if (options.clearPairing !== false) clearPairingFiles(accessoryUuidFor(mapperKind, numericId), this.ctx.logger);
 		await this.forgetFingerprint(numericId);
+		this.hksvBuilds.forget(numericId);
 		log.info("export-hap: unexposed device");
 	}
 	async attachMapper(entry) {
@@ -106845,9 +108834,13 @@ var ExportHapAddon = class extends BaseAddon {
 				ptzPulseMs: this.config.ptzPulseMs,
 				decodeMemos: this.decodeMemos,
 				hksvClipStore: this.hksvClipStore,
+				noteHksvOutcome: (outcome) => {
+					this.hksvBuilds.note(outcome);
+				},
 				hapDeviceSettings: {
 					streamPreference: entrySettings.streamPreference ?? "auto",
 					hksvRecording: resolveHksvRecording(entrySettings),
+					keepHomekitClips: resolveKeepHomekitClips(entrySettings),
 					multiTierService: resolveMultiTierService(entrySettings),
 					allowTranscode: entrySettings.allowTranscode !== false
 				}
@@ -106961,6 +108954,21 @@ var ExportHapAddon = class extends BaseAddon {
 	* whether the reconcile actually rebuilds anything. Shared by the two
 	* triggers below.
 	*/
+	/**
+	* The clips location moved. A DOORBELL, not a payload: the event names which
+	* row changed and the re-read is the authority (`StorageLocationsChangedPayload`
+	* says so itself). Dropping the mirror is all this does — the next clip
+	* resolves it again, and a missed event self-heals on the revalidation
+	* window, so nothing here gates on a fallible read (D49).
+	*/
+	subscribeStorageLocationsForClips() {
+		const unsubscribe = this.ctx.eventBus.subscribe({ category: EventCategory.StorageLocationsChanged }, () => {
+			this.hksvClipLocation?.invalidate();
+		});
+		this.ctx.addDisposer(async () => {
+			unsubscribe();
+		});
+	}
 	subscribeDeviceLifecycleForReconcile(category) {
 		const unsubscribe = this.ctx.eventBus.subscribe({ category }, (event) => {
 			const data = event.data;
@@ -107159,6 +109167,14 @@ var ExportHapAddon = class extends BaseAddon {
 					requiresRestart: true,
 					placement: { tab: "advanced" }
 				}),
+				this.field({
+					type: "number",
+					key: "clipRetentionDays",
+					label: "Keep HomeKit clips for (days)",
+					description: "CamStack keeps its own copy of every clip it sends to HomeKit Secure Video — HomeKit itself never gives one back. This is the fleet default; each camera can override it, and each can switch the copies off entirely. Clips are also capped at 200 per camera, 512 MB per camera and 4 GB overall — whichever limit is reached first wins, and the log names which one.",
+					default: DEFAULT_CONFIG.clipRetentionDays,
+					placement: { tab: "advanced" }
+				}),
 				this.field({
 					type: "number",
 					key: "ptzPulseMs",
@@ -107182,6 +109198,8 @@ var ExportHapAddon = class extends BaseAddon {
 		const multiTierKey = `hap:${deviceId}:multiTierService`;
 		const useBridgeKey = `hap:${deviceId}:useBridge`;
 		const allowTranscodeKey = `hap:${deviceId}:allowTranscode`;
+		const keepClipsKey = `hap:${deviceId}:keepClips`;
+		const clipRetentionKey = `hap:${deviceId}:clipRetentionDays`;
 		const mapper = this.exposed.get(String(deviceId)) ?? null;
 		const paired = mapper ? accessoryPaired(mapper.accessory) : false;
 		const bridged = mapper !== null && this.bridgeHost?.holds(mapper.accessory) === true;
@@ -107252,6 +109270,31 @@ var ExportHapAddon = class extends BaseAddon {
 				},
 				immediate: true
 			},
+			{
+				type: "boolean",
+				key: keepClipsKey,
+				label: "Keep CamStack copies of HomeKit clips",
+				description: "Save a copy of every clip sent to HomeKit Secure Video, on the “HomeKit Clips” storage location. HomeKit never gives a clip back, so a recording made with this off cannot be recovered later. Off saves the disk and one thumbnail decode per clip; the HomeKit recording itself is unchanged either way.",
+				style: "switch",
+				value: resolveKeepHomekitClips(settings),
+				showWhen: {
+					field: hksvKey,
+					equals: true
+				},
+				immediate: true
+			},
+			{
+				type: "number",
+				key: clipRetentionKey,
+				label: "Keep this camera’s clips for (days)",
+				description: `How long this camera’s kept clips survive before they are pruned, oldest first. Leave at ${this.config.clipRetentionDays} to follow the fleet default. The per-camera caps (200 clips, 512 MB) and the 4 GB overall cap still apply — whichever is reached first wins, and the prune log names it.`,
+				value: resolveClipRetentionDays(settings, this.config.clipRetentionDays),
+				showWhen: {
+					field: keepClipsKey,
+					equals: true
+				},
+				immediate: true
+			},
 			{
 				type: "boolean",
 				key: allowTranscodeKey,
@@ -107339,6 +109382,8 @@ var ExportHapAddon = class extends BaseAddon {
 		const useBridgeKey = `hap:${deviceId}:useBridge`;
 		const allowTranscodeKey = `hap:${deviceId}:allowTranscode`;
 		const multiTierKey = `hap:${deviceId}:multiTierService`;
+		const keepClipsKey = `hap:${deviceId}:keepClips`;
+		const clipRetentionKey = `hap:${deviceId}:clipRetentionDays`;
 		const enabledValue = enabledKey in patch ? Boolean(patch[enabledKey]) : wasEnabled;
 		const streamPreferenceRaw = streamPreferenceKey in patch ? patch[streamPreferenceKey] : current?.settings?.streamPreference;
 		const streamPreference = typeof streamPreferenceRaw === "string" && streamPreferenceRaw.trim().length > 0 ? streamPreferenceRaw : "auto";
@@ -107346,13 +109391,20 @@ var ExportHapAddon = class extends BaseAddon {
 		const useBridge = useBridgeKey in patch ? Boolean(patch[useBridgeKey]) : current?.settings?.useBridge !== false;
 		const allowTranscode = allowTranscodeKey in patch ? Boolean(patch[allowTranscodeKey]) : current?.settings?.allowTranscode !== false;
 		const multiTierService = multiTierKey in patch ? Boolean(patch[multiTierKey]) : resolveMultiTierService(current?.settings);
+		const keepClips = keepClipsKey in patch ? Boolean(patch[keepClipsKey]) : resolveKeepHomekitClips(current?.settings);
+		const clipRetentionDays = clipRetentionKey in patch ? resolveClipRetentionDays({
+			streamPreference,
+			clipRetentionDays: Number(patch[clipRetentionKey])
+		}, this.config.clipRetentionDays) : resolveClipRetentionDays(current?.settings, this.config.clipRetentionDays);
 		const nextSettings = {
 			...current?.settings ?? DEFAULT_DEVICE_SETTINGS,
 			streamPreference,
 			hksvRecording,
 			useBridge,
 			allowTranscode,
-			multiTierService
+			multiTierService,
+			keepClips,
+			clipRetentionDays
 		};
 		if (!enabledValue) {
 			if (wasEnabled) await this.unexposeDevice(deviceIdStr);
@@ -107365,6 +109417,7 @@ var ExportHapAddon = class extends BaseAddon {
 		}
 		const currentPref = current?.settings?.streamPreference ?? "auto";
 		const currentHksv = resolveHksvRecording(current?.settings);
+		const currentKeepClips = resolveKeepHomekitClips(current?.settings);
 		const mapperKind = current?.mapperKind ?? "generic";
 		const wasBridged = shouldBridge({
 			mapperKind,
@@ -107375,7 +109428,7 @@ var ExportHapAddon = class extends BaseAddon {
 			useBridge
 		});
 		await this.updateEntrySettings(deviceIdStr, nextSettings);
-		if (currentPref !== streamPreference || currentHksv !== hksvRecording || wasBridged !== willBridge) {
+		if (currentPref !== streamPreference || currentHksv !== hksvRecording || currentKeepClips !== keepClips || wasBridged !== willBridge) {
 			log.info("export-hap: per-camera export settings changed — refreshing accessory", { meta: {
 				streamPreference: {
 					from: currentPref,
@@ -107385,6 +109438,10 @@ var ExportHapAddon = class extends BaseAddon {
 					from: currentHksv,
 					to: hksvRecording
 				},
+				keepClips: {
+					from: currentKeepClips,
+					to: keepClips
+				},
 				bridged: {
 					from: wasBridged,
 					to: willBridge
@@ -107399,6 +109456,57 @@ var ExportHapAddon = class extends BaseAddon {
 		}
 		return { success: true };
 	}
+	/**
+	* Host the clip byte + still routes, and never let a host without the
+	* facility take the addon down with it: a data plane is an enhancement to an
+	* addon that already works, so a failure here degrades the clip surface and
+	* nothing else. It is LOGGED, because a branch that drops work silently
+	* reads as "never happened".
+	*
+	* `authenticated`, not `admin`, and NO TOKEN in either URL: the hub's
+	* `/addon/<id>/<prefix>` proxy takes the session cookie, exactly as the
+	* recorder's own playback plane does (D549 22).
+	*/
+	async serveHksvClipPlanes() {
+		const store = this.hksvClipStore;
+		if (store === null) return;
+		const planes = createHksvClipPlanes({
+			logger: this.ctx.logger.child("hksv-clips"),
+			artifactPath: (deviceId, stem, artifact) => store.artifactPath(deviceId, stem, artifact)
+		});
+		try {
+			const media = await this.ctx.dataPlane?.serve({
+				prefix: planes.mediaPrefix,
+				access: "authenticated",
+				handler: planes.mediaHandler
+			});
+			const thumb = await this.ctx.dataPlane?.serve({
+				prefix: planes.thumbPrefix,
+				access: "authenticated",
+				handler: planes.thumbHandler
+			});
+			this.hksvClipPlanes = planes;
+			this.ctx.logger.info("export-hap: HomeKit clip data planes served", { meta: {
+				mediaPath: `/addon/${EXPORT_HAP_ADDON_ID}/${planes.mediaPrefix}`,
+				thumbPath: `/addon/${EXPORT_HAP_ADDON_ID}/${planes.thumbPrefix}`,
+				mediaServed: media !== void 0,
+				thumbServed: thumb !== void 0
+			} });
+		} catch (err) {
+			this.ctx.logger.warn("export-hap: HomeKit clip data planes failed to serve — clips will list but not play", { meta: { error: errMsg(err) } });
+		}
+	}
+	/**
+	* The client path of one clip artifact.
+	*
+	* Composed from the SERVED prefixes when the planes are up, so a URL is
+	* never minted for a route that does not exist; the constants are the
+	* fallback for the one window between registration and `serve` returning.
+	*/
+	hksvClipUrl(kind, deviceId, stem) {
+		const planes = this.hksvClipPlanes;
+		return `/addon/${EXPORT_HAP_ADDON_ID}/${kind === "media" ? planes?.mediaPrefix ?? "hksv-clip" : planes?.thumbPrefix ?? "hksv-clip-thumb"}/${String(deviceId)}/${stem}.${kind === "media" ? "mp4" : "jpg"}`;
+	}
 	findEntry(deviceId) {
 		const id = String(deviceId);
 		return this.config.exposed.find((e) => e.deviceId === id) ?? null;
@@ -107415,4 +109523,4 @@ function errMsg(err) {
 	return err instanceof Error ? err.message : String(err);
 }
 //#endregion
-export { ExportHapAddon, ExportHapAddon as default, unpublishAccessory as i, initHapStorage as n, publishStandalone as r, resolveHksvRecording, resolveMultiTierService, deriveUsername as t };
+export { DEFAULT_CLIP_RETENTION_DAYS, EXPORT_HAP_ADDON_ID, ExportHapAddon, ExportHapAddon as default, describeHksvCamera, unpublishAccessory as i, initHapStorage as n, publishStandalone as r, resolveClipRetentionDays, resolveHksvRecording, resolveKeepHomekitClips, resolveMultiTierService, deriveUsername as t };