@camstack/system 1.2.248 → 1.2.250

package/dist/builtins/snapshot/index.mjs

@@ -1,8 +1,10 @@
-import { Bt as snapshotCapability, Cn as EventCategory, G as deriveBatteryPresence, Gt as streamQualityLabel, I as bareAddonId, L as batteryCapability, Xt as errMsg, Zt as BaseAddon, gn as nodePin, i as BatteryStatusSchema, rn as DeviceType, tn as DeviceFeature } from "../../dist-C8v6cK8N.mjs";
+import { Bt as snapshotCapability, Cn as EventCategory, G as deriveBatteryPresence, Gt as streamQualityLabel, I as bareAddonId, L as batteryCapability, Xt as errMsg, Zt as BaseAddon, gn as nodePin, i as BatteryStatusSchema, rn as DeviceType, tn as DeviceFeature } from "../../dist-BHlcm97I.mjs";
 import { i as renderCourtesyOverlayJpeg, n as courtesyCacheKey, r as renderCourtesyJpeg } from "../../snapshot-courtesy-CZPvteq2.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
 import { signExpiringUrl, verifyExpiringUrl } from "@camstack/types/node";
+import { join } from "node:path";
+import { promises } from "node:fs";
 import { execFile } from "node:child_process";
 import sharp from "sharp";
 //#region src/builtins/snapshot/snapshot-cache.ts
@@ -123,6 +125,105 @@ var SnapshotCache = class {
 	}
 };
 //#endregion
+//#region src/builtins/snapshot/snapshot-durable-store.ts
+/**
+* The last good frame per camera, on disk, so it outlives the process.
+*
+* ## Why
+*
+* The snapshot cache is RAM-only and says so: *"after a hub restart this
+* legitimately answers nothing and the generated card is the picture"*. That is
+* accurate and it is also the whole defect, because the cameras that most need
+* a cached frame are the ones that can never be asked for a fresh one. A
+* sleeping battery camera refuses every snapshot that does not carry `force`,
+* and the sentry deliberately never passes it — forcing would wake the very
+* camera the window exists so as not to disturb.
+*
+* Measured 2026-09-17: the baby monitor showed the courtesy card all morning.
+* Nothing was broken. Three server updates had emptied the cache, and the
+* camera had been asleep since.
+*
+* ## Shape
+*
+* One file per device under the addon's OWN private directory (`ctx.dataDir` —
+* `<nodeDataDir>/addons-data/<addonId>`, which the addon owns exclusively), and
+* it is overwritten rather than appended: what is wanted is A recent frame, not
+* a history. A history here would grow without a reaper and compete with the
+* recordings for the same disk.
+*
+* Writes are THROTTLED per device. Snapshots are captured far more often than a
+* process restarts, and persisting every one buys nothing — one recent frame is
+* the entire value.
+*
+* Nothing here throws. The caller already has its picture; persistence is a
+* bonus for the NEXT boot, and a disk that refuses must never cost a snapshot
+* that succeeded. A frame that cannot be read is reported ABSENT, never as an
+* error and never as an empty buffer — absent is the truth and the courtesy
+* card is the correct answer to it.
+*/
+/** One recent frame is the value; a newer one is not worth the disk. */
+var DEFAULT_MIN_INTERVAL_MS = 6e4;
+/** Its own subdirectory, so the addon's other state is never mistaken for a frame. */
+var SUBDIR = "last-frame";
+var SnapshotDurableStore = class {
+	dir;
+	minIntervalMs;
+	now;
+	/** Last write per device, so the throttle survives without touching disk. */
+	lastWriteMs = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.dir = join(options.dataDir, SUBDIR);
+		this.minIntervalMs = options.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS;
+		this.now = options.now ?? (() => Date.now());
+	}
+	/** @returns whether the frame was written. `false` is throttled or refused. */
+	async put(deviceId, jpeg) {
+		if (jpeg.length === 0) return false;
+		const at = this.now();
+		const previous = this.lastWriteMs.get(deviceId);
+		if (previous !== void 0 && at - previous < this.minIntervalMs) return false;
+		try {
+			await promises.mkdir(this.dir, { recursive: true });
+			const target = this.pathFor(deviceId);
+			const staging = `${target}.writing`;
+			await promises.writeFile(staging, jpeg);
+			await promises.rename(staging, target);
+			this.lastWriteMs.set(deviceId, at);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/** The frame from a previous process, or `null` — which is a real answer. */
+	async get(deviceId) {
+		return (await this.getDated(deviceId))?.jpeg ?? null;
+	}
+	/**
+	* The frame WITH the moment it was captured.
+	*
+	* The age travels with it because everything downstream decides on age, and
+	* a frame restored from disk that claims to be new is worse than no frame:
+	* it would satisfy a freshness gate it has no right to pass. The file's own
+	* mtime is the honest answer — it is when this frame was written.
+	*/
+	async getDated(deviceId) {
+		try {
+			const path = this.pathFor(deviceId);
+			const [jpeg, stat] = await Promise.all([promises.readFile(path), promises.stat(path)]);
+			if (jpeg.length === 0) return null;
+			return {
+				jpeg,
+				capturedAtMs: stat.mtimeMs
+			};
+		} catch {
+			return null;
+		}
+	}
+	pathFor(deviceId) {
+		return join(this.dir, `${String(deviceId)}.jpg`);
+	}
+};
+//#endregion
 //#region src/builtins/snapshot/snapshot-coalescing.ts
 /**
 * Pure, side-effect-free coalescing / stale-while-revalidate / bounded-pool
@@ -942,6 +1043,26 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	*/
 	/** Cameras resting after a native miss — see `snapshot-fatigue.ts`. */
 	fatigue = new NativeSnapshotFatigue();
+	/**
+	* The last good frame per camera, on disk, so it outlives the process.
+	*
+	* The cache above is RAM-only and the cameras that most need it are the ones
+	* that can never be asked for a fresh frame: a sleeping battery camera
+	* refuses every snapshot without `force`, and the background callers that
+	* would want one deliberately never pass it. Measured 2026-09-17 — the baby
+	* monitor showed the courtesy card all morning because three server updates
+	* had emptied this cache and the camera had been asleep since.
+	*/
+	durableStore = null;
+	/**
+	* Built on first use, never in a field initializer: `ctx` does not exist
+	* until `initialize()`, and reading it at construction throws
+	* "ctx accessed before initialize()" for the whole addon.
+	*/
+	get durable() {
+		this.durableStore ??= new SnapshotDurableStore({ dataDir: this.ctx.dataDir });
+		return this.durableStore;
+	}
 	cache = new SnapshotCache({ onEvict: (deviceId, streamId, reason) => {
 		this.ctx.logger.debug("snapshot cache evicted", {
 			tags: { deviceId },
@@ -1605,7 +1726,8 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 					ageMs: hit ? now - hit.ts : null
 				}
 			});
-			return await this.stateImage(deviceId, state.reason, deviceName, hit);
+			const base = hit ?? await this.durableEntry(deviceId);
+			return await this.stateImage(deviceId, state.reason, deviceName, base);
 		}
 		const effectiveMaxAgeMs = Math.min(maximumCacheAgeMs, Math.max(0, effectiveMaxAgeS(prefs, isBatteryDevice) * 1e3));
 		const decision = decideSnapshotServe({
@@ -1760,6 +1882,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 						ts: now,
 						streamId: effectiveStreamId ?? null
 					});
+					this.durable.put(deviceId, Buffer.from(result.base64, "base64"));
 					return {
 						ok: true,
 						image: result
@@ -1807,6 +1930,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 					ts: now,
 					streamId: effectiveStreamId ?? null
 				});
+				this.durable.put(deviceId, Buffer.from(fallback.base64, "base64"));
 				return {
 					ok: true,
 					image: fallback
@@ -2272,6 +2396,23 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	* the answer by itself; if it cannot be decoded, fall back to the generated
 	* courtesy background rather than leaking an unlabelled stale frame.
 	*/
+	/** The persisted frame as a cache entry, with its real age. */
+	async durableEntry(deviceId) {
+		const dated = await this.durable.getDated(deviceId);
+		if (dated === null) return void 0;
+		this.ctx.logger.debug("snapshot: serving the frame kept from a previous process", {
+			tags: { deviceId },
+			meta: { ageMs: Date.now() - dated.capturedAtMs }
+		});
+		return {
+			data: {
+				base64: dated.jpeg.toString("base64"),
+				contentType: "image/jpeg"
+			},
+			ts: dated.capturedAtMs,
+			streamId: null
+		};
+	}
 	async stateImage(deviceId, reason, deviceName, hit) {
 		const resolvedName = deviceName ?? `#${String(deviceId)}`;
 		if (!hit) return await this.courtesyImage(deviceId, reason, resolvedName);

package/dist/builtins/snapshot/snapshot-durable-store.d.ts

@@ -0,0 +1,32 @@
+export interface SnapshotDurableStoreOptions {
+    /** `ctx.dataDir` — the addon's exclusive directory. */
+    readonly dataDir: string;
+    readonly minIntervalMs?: number;
+    /** Injectable for tests; `Date.now` otherwise. */
+    readonly now?: () => number;
+}
+export declare class SnapshotDurableStore {
+    private readonly dir;
+    private readonly minIntervalMs;
+    private readonly now;
+    /** Last write per device, so the throttle survives without touching disk. */
+    private readonly lastWriteMs;
+    constructor(options: SnapshotDurableStoreOptions);
+    /** @returns whether the frame was written. `false` is throttled or refused. */
+    put(deviceId: number, jpeg: Buffer): Promise<boolean>;
+    /** The frame from a previous process, or `null` — which is a real answer. */
+    get(deviceId: number): Promise<Buffer | null>;
+    /**
+     * The frame WITH the moment it was captured.
+     *
+     * The age travels with it because everything downstream decides on age, and
+     * a frame restored from disk that claims to be new is worse than no frame:
+     * it would satisfy a freshness gate it has no right to pass. The file's own
+     * mtime is the honest answer — it is when this frame was written.
+     */
+    getDated(deviceId: number): Promise<{
+        jpeg: Buffer;
+        capturedAtMs: number;
+    } | null>;
+    private pathFor;
+}

package/dist/builtins/snapshot/snapshot.addon.d.ts

@@ -38,6 +38,23 @@ export declare class SnapshotAddon extends BaseAddon<SnapshotAddonConfig> {
      */
     /** Cameras resting after a native miss — see `snapshot-fatigue.ts`. */
     private readonly fatigue;
+    /**
+     * The last good frame per camera, on disk, so it outlives the process.
+     *
+     * The cache above is RAM-only and the cameras that most need it are the ones
+     * that can never be asked for a fresh frame: a sleeping battery camera
+     * refuses every snapshot without `force`, and the background callers that
+     * would want one deliberately never pass it. Measured 2026-09-17 — the baby
+     * monitor showed the courtesy card all morning because three server updates
+     * had emptied this cache and the camera had been asleep since.
+     */
+    private durableStore;
+    /**
+     * Built on first use, never in a field initializer: `ctx` does not exist
+     * until `initialize()`, and reading it at construction throws
+     * "ctx accessed before initialize()" for the whole addon.
+     */
+    private get durable();
     private readonly cache;
     /** Card-sized derivatives of the frames above, keyed by width and validated
      *  against the source frame's timestamp. */
@@ -487,6 +504,8 @@ export declare class SnapshotAddon extends BaseAddon<SnapshotAddonConfig> {
      * the answer by itself; if it cannot be decoded, fall back to the generated
      * courtesy background rather than leaking an unlabelled stale frame.
      */
+    /** The persisted frame as a cache entry, with its real age. */
+    private durableEntry;
     private stateImage;
     /**
      * Single-trip device lookup against device-manager — memoized for

package/dist/builtins/sqlite-storage/filesystem-storage.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-CpXBoZOv.js");
+const require_dist = require("../../dist-BW7x4kAI.js");
 let node_crypto = require("node:crypto");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");

package/dist/builtins/sqlite-storage/filesystem-storage.addon.mjs

@@ -1,4 +1,4 @@
-import { Wt as storageProviderCapability, Zt as BaseAddon, nt as filesystemBrowseCapability } from "../../dist-C8v6cK8N.mjs";
+import { Wt as storageProviderCapability, Zt as BaseAddon, nt as filesystemBrowseCapability } from "../../dist-BHlcm97I.mjs";
 import { randomUUID } from "node:crypto";
 import { mkdir, readdir, realpath, statfs } from "node:fs/promises";
 import * as path$1 from "node:path";

package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-CpXBoZOv.js");
+const require_dist = require("../../dist-BW7x4kAI.js");
 const require_hub_cap_forward = require("../../hub-cap-forward-DmHNjbB0.js");
 let zod = require("zod");
 let node_crypto = require("node:crypto");

package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.mjs

@@ -1,4 +1,4 @@
-import { Cn as EventCategory, Ct as modeMayWrite, D as StorageLocationTypeSchema, E as StorageLocationModeSchema, Ht as storageMigrationCapability, Mt as resolveLocationMode, O as StorageMigrationJobSchema, Rt as settingsStoreCapability, T as StorageCleanupJobSchema, Vt as storageCapability, Yt as withLocationMode, Zt as BaseAddon, _ as REDACTED_SECRET, _n as parseJsonObject, bt as mayReadLocation, et as evictionPolicyOfLocation, it as gbToBytes, m as LegacyStorageLocationDefaultSchema, pt as legacyModeOf, st as isLocationEnabled, xt as mayWriteToLocation, z as collectSecretConfigKeys } from "../../dist-C8v6cK8N.mjs";
+import { Cn as EventCategory, Ct as modeMayWrite, D as StorageLocationTypeSchema, E as StorageLocationModeSchema, Ht as storageMigrationCapability, Mt as resolveLocationMode, O as StorageMigrationJobSchema, Rt as settingsStoreCapability, T as StorageCleanupJobSchema, Vt as storageCapability, Yt as withLocationMode, Zt as BaseAddon, _ as REDACTED_SECRET, _n as parseJsonObject, bt as mayReadLocation, et as evictionPolicyOfLocation, it as gbToBytes, m as LegacyStorageLocationDefaultSchema, pt as legacyModeOf, st as isLocationEnabled, xt as mayWriteToLocation, z as collectSecretConfigKeys } from "../../dist-BHlcm97I.mjs";
 import { t as HUB_CAP_FWD_ACTION } from "../../hub-cap-forward-BdT320dq.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";

package/dist/builtins/system-config/system-config.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-CpXBoZOv.js");
+const require_dist = require("../../dist-BW7x4kAI.js");
 //#region src/builtins/system-config/system-config.addon.ts
 /**
 * Built-in `system-config` addon — Phase 4 of the settings redesign.

package/dist/builtins/system-config/system-config.addon.mjs

@@ -1,4 +1,4 @@
-import { Xt as errMsg, Zt as BaseAddon, mn as hydrateSchema } from "../../dist-C8v6cK8N.mjs";
+import { Xt as errMsg, Zt as BaseAddon, mn as hydrateSchema } from "../../dist-BHlcm97I.mjs";
 //#region src/builtins/system-config/system-config.addon.ts
 /**
 * Built-in `system-config` addon — Phase 4 of the settings redesign.

package/dist/builtins/winston-logging/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-CpXBoZOv.js");
+const require_dist = require("../../dist-BW7x4kAI.js");
 const require_formatter = require("../../formatter-DqAKDlvN.js");
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);

package/dist/builtins/winston-logging/index.mjs

@@ -1,4 +1,4 @@
-import { Zt as BaseAddon, _t as logDestinationCapability } from "../../dist-C8v6cK8N.mjs";
+import { Zt as BaseAddon, _t as logDestinationCapability } from "../../dist-BHlcm97I.mjs";
 import { t as formatLogLine } from "../../formatter-B7qW8bPJ.mjs";
 import * as path$1 from "node:path";
 import path from "node:path";

package/dist/{dist-C8v6cK8N.mjs → dist-BHlcm97I.mjs}

@@ -690,7 +690,7 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	return EventCategory;
 }({});
 //#endregion
-//#region ../types/dist/sleep-BDR76Ykr.mjs
+//#region ../types/dist/sleep-B1y0Fo1U.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -8999,7 +8999,7 @@ var streamBrokerCapability = {
 		*  - the signal is ENABLED for this camera (the operator's per-camera
 		*    choice — a camera may declare a signal the operator does not want
 		*    waking anything), and
-		*  - a consumer is actually attached and waiting on the prestream. Waking
+		*  - a consumer is actually attached and waiting on the sentry. Waking
 		*    a camera nobody is watching is the one thing a battery camera must
 		*    never do, and a signal arriving with no consumer is exactly that.
 		*
@@ -32804,14 +32804,81 @@ var privacyMaskCapability = {
 	*  whether persisting is worth a SQLite commit. */
 	volatileStateFields: ["lastFetchedAt"]
 };
+/**
+* What a preset id DOES on this camera.
+*
+* On several PTZ firmwares the preset namespace is shared: low ids are stored
+* positions, a reserved band triggers camera FUNCTIONS. The dispensa camera
+* (Hikvision) returns its own reserved band in the preset list, named by the
+* firmware:
+*
+*   34 Back to origin · 39 Day mode · 40 Night mode · 46 Day/Night Auto Mode
+*   92 Set manual limits · 93 Save manual limits · 94 Remote reboot
+*   95 Call OSD menu
+*
+* We used to hand all of these to the UI as ordinary presets. Saving over one
+* is what produced `PUT /ISAPI/PTZCtrl/channels/1/presets/34 -> HTTP 500`: the
+* camera refusing to let "Back to origin" be overwritten, surfaced to the
+* operator as a transport failure.
+*
+* A function preset stays fully usable as a DESTINATION -- `goToPreset('34')`
+* is the single most useful thing that camera can do. Only `savePreset` and
+* `deletePreset` are gated.
+*/
+var PtzPresetFunctionSchema = z.enum([
+	"home",
+	"day-mode",
+	"night-mode",
+	"day-night-auto",
+	"set-limits",
+	"save-limits",
+	"reboot",
+	"osd-menu"
+]);
 var PtzPresetSchema = z.object({
 	id: z.string(),
-	name: z.string()
+	name: z.string(),
+	/**
+	* The firmware function this id performs, when the provider KNOWS the id is
+	* reserved. `null` = an ordinary stored position, OR a reserved id this
+	* provider does not recognise -- the two are told apart by `writable`.
+	*/
+	fn: PtzPresetFunctionSchema.nullable(),
+	/**
+	* Whether `savePreset` / `deletePreset` may target this id. A provider sets
+	* it false only for a band it KNOWS is reserved; where the firmware is not
+	* documented it stays true and a refusal comes from the camera, named.
+	*/
+	writable: z.boolean()
 });
+/**
+* Where the head is pointing -- per axis, and `null` when the driver cannot
+* read it.
+*
+* It used to be three REQUIRED numbers, which left a provider that cannot read
+* position no way to say so. All four said `0`:
+*
+*   reolink   `return { pan: 0, tilt: 0, zoom: 0 }`  "until a position-query
+*                                                     path lands upstream"
+*   hikvision stub, "firmware-dependent and frequently absent"
+*   amcrest   stub, "no generic absolute-position read for this model family"
+*   onvif     throws
+*
+* So every consumer asking where a camera points was told "perfectly centred"
+* by four cameras that had never looked. That is D393 -- a measurement that
+* FAILED is `null`, never `0`, and the type says so all the way to the
+* decision -- the same shape as the unreadable `statfs` folded into "0 bytes of
+* headroom", which evacuated a healthy disk.
+*
+* D393 also says to check for a narrower structural TWIN of the result type.
+* There is one: `PtzStatusSchema` extends this, so the lie had already
+* propagated into `getStatus`, which is the surface `getPosition`'s own comment
+* tells callers to migrate to.
+*/
 var PtzPositionSchema = z.object({
-	pan: z.number(),
-	tilt: z.number(),
-	zoom: z.number()
+	pan: z.number().nullable(),
+	tilt: z.number().nullable(),
+	zoom: z.number().nullable()
 });
 var PtzMoveCommandSchema = z.object({
 	pan: z.number().optional(),
@@ -32833,7 +32900,72 @@ var PtzOptionsSchema = z.object({
 	maxPresets: z.number().optional(),
 	/** Whether the camera exposes a controllable autofocus toggle
 	*  (boolean `hasX` per the getOptions availability convention). */
-	hasAutofocus: z.boolean()
+	hasAutofocus: z.boolean(),
+	/**
+	* How many distinct speeds this camera's NATIVE scale offers.
+	*
+	* The cap's `speed` is normalized 0..1 and each provider maps it down --
+	* Baichuan 1..63, Dahua 1..8, ISAPI's percentage -100..100. The normalized
+	* value hides how coarse that really is: asking an amcrest for `0.37` is
+	* meaningless, because it has eight steps and three of them round to the
+	* same one. A loop that tunes its own gain has to know the granularity of
+	* the knob it is turning.
+	*
+	* `null` = the driver does not know, or the scale is continuous (ONVIF takes
+	* a float). Never a made-up number.
+	*/
+	speedSteps: z.number().int().positive().nullable(),
+	/**
+	* How long ONE `move` pulse runs on this driver, ms.
+	*
+	* `move` is a self-terminating burst everywhere, but every provider hardcoded
+	* its own duration in private -- 200 reolink, 350 amcrest, 500 hikvision,
+	* 1000 onvif -- so no caller could read it. It is the DENOMINATOR of "how far
+	* did the head travel per pulse": without it a measured displacement has no
+	* gain to be divided into.
+	*
+	* `null` = the driver cannot say.
+	*/
+	moveImpulseMs: z.number().int().positive().nullable()
+});
+/**
+* Which preset `goHome` goes to, and WHO decided.
+*
+* `goHome` used to be three vendor "conventions" written in three comments --
+* Reolink preset 0, Hikvision preset '1', Dahua preset 1 -- and on this fleet
+* not one of the three cameras honours its own:
+*
+*   592  Videocamera camera Daniel (reolink)   preset 0 holds "stanza"
+*   1438 Videocamera dispensa (hikvision)      preset 1 holds "Credenza"
+*   3836 Videocamera studio (amcrest)          preset 1 holds "Preset1"
+*
+* So `goHome` meant "go wherever the operator happened to save in slot 0 or 1",
+* and two of the three swallowed the failure in a bare `catch`. For autotrack
+* this is the HOTTEST path -- it runs every time a subject is released -- so it
+* needs an answer that is true per camera and audible when it is missing.
+*
+* `source` is what makes it honest:
+*   - `operator` -- picked in the UI, stored by the provider.
+*   - `firmware` -- the camera itself named a preset `fn: 'home'` (Hikvision's
+*     "Back to origin"), adopted as the default with nothing to configure.
+*   - `native`   -- the driver homes WITHOUT a preset at all. ONVIF does:
+*     `goHome` is `ptzAbsoluteMove({x:0, y:0, zoom:0})`. `presetId` is null and
+*     that is not a failure -- there is nothing to pick, and the UI must offer
+*     no picker.
+*   - `none`     -- nothing is configured and the camera names nothing.
+*     `goHome` REFUSES rather than moving the head somewhere arbitrary.
+*
+* `source === 'none'` is the refusal condition, NOT `presetId === null`: the
+* native case has no preset and homes perfectly well.
+*/
+var PtzHomePresetSchema = z.object({
+	presetId: z.string().nullable(),
+	source: z.enum([
+		"operator",
+		"firmware",
+		"native",
+		"none"
+	])
 });
 var ptzCapability = {
 	name: "ptz",
@@ -32874,7 +33006,25 @@ var ptzCapability = {
 			auth: "admin"
 		}),
 		getOptions: method(z.object({ deviceId: z.number() }), PtzOptionsSchema),
+		/**
+		* Move to the camera's configured home preset. THROWS when
+		* `getHomePreset()` resolves to `none` -- a head that did not move must
+		* never look like a head that went home.
+		*/
 		goHome: method(z.object({ deviceId: z.number() }), z.void(), { kind: "mutation" }),
+		/** Which preset `goHome` targets, and who decided it. */
+		getHomePreset: method(z.object({ deviceId: z.number() }), PtzHomePresetSchema),
+		/**
+		* Pin the home preset for this camera. `null` clears the operator's choice
+		* and falls back to whatever the firmware names, or to `none`.
+		*/
+		setHomePreset: method(z.object({
+			deviceId: z.number(),
+			presetId: z.string().nullable()
+		}), z.void(), {
+			kind: "mutation",
+			auth: "admin"
+		}),
 		/**
 		* Pull the current PTZ position. Redundant with the auto-injected
 		* `getStatus` method (see `status` below); kept for callers that
@@ -42271,6 +42421,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "delete"
 	},
+	"ptz.getHomePreset": {
+		capName: "ptz",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"ptz.getOptions": {
 		capName: "ptz",
 		capScope: "device",
@@ -42319,6 +42475,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"ptz.setHomePreset": {
+		capName: "ptz",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"ptz.stop": {
 		capName: "ptz",
 		capScope: "device",
@@ -45492,6 +45654,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"ptz.getHomePreset": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"ptz.getOptions": [{
 		name: "deviceId",
 		form: "single",
@@ -45532,6 +45699,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"ptz.setHomePreset": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"ptz.stop": [{
 		name: "deviceId",
 		form: "single",