@camstack/system 1.2.275 → 1.2.276

package/dist/{dist-CYXhwfDf.js → dist-D_OlSf31.js}

@@ -691,7 +691,7 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	return EventCategory;
 }({});
 //#endregion
-//#region ../types/dist/sleep-CiR4z7r9.mjs
+//#region ../types/dist/sleep-CopaBJss.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -892,6 +892,12 @@ var WELL_KNOWN_TAB_MAP = Object.fromEntries([
 		icon: "circle-dot",
 		order: 40
 	},
+	{
+		id: "clips",
+		label: "Clips",
+		icon: "clapperboard",
+		order: 41
+	},
 	{
 		id: "engine",
 		label: "Inference Engine",
@@ -2724,6 +2730,7 @@ function toNodeId(idOrRunnerId) {
 function resolveCapMount(def) {
 	if (def.mount) return def.mount;
 	if (def.deviceNative === true) return { kind: "device-native" };
+	if (def.scope === "device" && def.kind === "wrapper") return { kind: "device-scoped" };
 	if (def.mode === "collection") return { kind: "collection" };
 	return { kind: "singleton" };
 }
@@ -10380,6 +10387,33 @@ function objectInputDeclaresAddonId(schema) {
 	const shape = direct !== void 0 && direct !== null ? direct : resolveDefShape(schema._def?.shape);
 	return shape !== void 0 && shape !== null && typeof shape === "object" && Object.prototype.hasOwnProperty.call(shape, "addonId");
 }
+/**
+* True when an OBJECT input schema declares a top-level, REQUIRED, numeric
+* `deviceId` — i.e. the method names exactly one device on every call.
+*
+* This is the question the per-device dispatcher asks at runtime
+* (`requireDeviceScoped`: `typeof input.deviceId !== 'number'` → BAD_REQUEST),
+* asked once at build time instead. A `device-scoped` cap's method that cannot
+* answer it has no device to resolve for and therefore resolves through the
+* cap's SYSTEM provider (`cap-router-builder.ts`) — the same destination
+* `systemOnly` names explicitly. Without this, flipping the mount would 400
+* every batch (`deviceIds`), fleet-wide (`z.void()`) and job-keyed method on
+* the eight device-scoped wrapper caps.
+*
+* Structural, never a name heuristic over source text: the field must resolve
+* to `z.number()` and must NOT be wrapped in `optional` / `nullable` /
+* `default` — an absent value is exactly the input the dispatcher rejects.
+*/
+function objectInputDeclaresRequiredDeviceId(schema) {
+	if (schema === null || typeof schema !== "object" && typeof schema !== "function") return false;
+	const direct = schema.shape;
+	const shape = direct !== void 0 && direct !== null ? direct : resolveDefShape(schema._def?.shape);
+	if (shape === void 0 || shape === null || typeof shape !== "object") return false;
+	const field = shape["deviceId"];
+	if (field === void 0 || field === null) return false;
+	const def = field._def;
+	return field.constructor?.name === "ZodNumber" || def?.type === "number" || def?.typeName === "ZodNumber";
+}
 /** `_def.shape` may be a thunk (Zod defers object-shape evaluation) or a plain record. */
 function resolveDefShape(defShape) {
 	return typeof defShape === "function" ? defShape() : defShape;
@@ -13210,14 +13244,30 @@ var deviceManagerCapability = {
 		*/
 		getAllBindings: method(zod.z.object({}), zod.z.array(DeviceBindingsForDeviceSchema)),
 		/**
-		* Activate (or deactivate) a wrapper addon for a (device, cap) pair.
-		* Persists the binding via ctx.settings. active=false clears the wrapper
-		* (falls back to native if registered).
+		* Activate (or deactivate) a wrapper addon — or ONE of its sources — for a
+		* (device, cap) pair.
+		*
+		* Persists the binding via ctx.settings; `active: false` on a SINGLETON cap
+		* clears the wrapper (falling back to native if one is registered). On a
+		* COLLECTION cap it adds to the per-device DENY set instead, and the
+		* wrapper binding is left exactly as it was — a cap with several sources
+		* has no "which one" for `getBindings` to answer (D556).
+		*
+		* `sourceId` is what makes the switch match its label. One addon can serve
+		* several of a device's sources (`addon-provider-reolink` answers a hub
+		* child with `native:reolink:onboard` AND `native:reolink:hub`), so a
+		* toggle keyed by addon would turn off both while saying it turned off one
+		* — the D62 defect with the polarity reversed (D557). Naming the source
+		* denies exactly that source. OMITTING it keeps the cap-wide meaning
+		* D556 shipped: every source this addon serves for this device, which is
+		* also how a deny entry persisted before the re-key is still read.
 		*/
 		setWrapperActive: method(zod.z.object({
 			deviceId: zod.z.number(),
 			capName: zod.z.string(),
 			wrapperAddonId: zod.z.string(),
+			/** The `ClipSource.source` id to toggle. Absent = all of the addon's. */
+			sourceId: zod.z.string().optional(),
 			active: zod.z.boolean()
 		}), zod.z.void(), {
 			kind: "mutation",
@@ -25975,41 +26025,299 @@ var ClipSchema = zod.z.object({
 	holes: zod.z.array(zod.z.object({
 		startMs: zod.z.number(),
 		endMs: zod.z.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: zod.z.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: zod.z.object({ reason: zod.z.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: zod.z.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: zod.z.array(zod.z.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: zod.z.array(zod.z.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: zod.z.object({
+		sub: zod.z.object({
+			id: zod.z.string(),
+			bytes: zod.z.number().optional()
+		}).optional(),
+		main: zod.z.object({
+			id: zod.z.string(),
+			bytes: zod.z.number().optional()
+		}).optional()
+	}).optional(),
+	/** The camera says it holds a sub-stream copy of this recording. */
+	supportSub: zod.z.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: zod.z.boolean().optional(),
+	/** Why {@link playable} is false, verbatim (`no-file-for-window`). */
+	unplayableReason: zod.z.string().optional()
 });
 var ClipPlaybackSchema = zod.z.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: zod.z.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: zod.z.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: zod.z.array(zod.z.string()).optional(),
 	token: zod.z.string().optional()
 });
+/**
+* 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.
+*/
+var ClipSourceAvailabilitySchema = zod.z.object({
+	state: zod.z.enum([
+		"ok",
+		"sleeping",
+		"unreachable",
+		"no-storage",
+		"index-empty"
+	]),
+	/** Free text, shown verbatim. Names the camera's own refusal when there is one. */
+	reason: zod.z.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: zod.z.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 = zod.z.object({
+	/** The value this source stamps on {@link ClipSchema.source}, and the prefix
+	*  of every clip id it mints. `getClipPlayback` routes on it. */
+	source: zod.z.string(),
+	/** Operator-facing name of the source ("CamStack recordings", "SD card"). */
+	label: zod.z.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: `addon-provider-reolink`
+	* answers a hub child with both `native:reolink:onboard` and
+	* `native:reolink:hub`, which is why the per-device switch is keyed by
+	* SOURCE and not by this (D555).
+	*
+	* 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: zod.z.string().optional(),
+	/**
+	* Which API this source resolved to FOR THIS CAMERA, when it has a choice.
+	*
+	* A source may cover one store through more than one surface — the Reolink
+	* provider reads a hub child through the parent's event log and a standalone
+	* through its own file list, because that is what each camera answers. The
+	* CHOICE is the provider's, made from what the camera is, and is never a row
+	* the operator has to understand; but it is REPORTED, because a source that
+	* silently reads a different API on two cameras and then behaves differently
+	* is the thing nobody can debug later. Absent when the source has only one
+	* way to read its store.
+	*/
+	via: zod.z.string().optional(),
+	availability: ClipSourceAvailabilitySchema,
+	/**
+	* The operator switched this source OFF for this camera.
+	*
+	* Deliberately NOT a member of {@link ClipSourceAvailabilitySchema}'s
+	* vocabulary. That enum models what the source CAN do — a sleeping camera, an
+	* unmounted card, an index that disagrees with its own calendar — and a
+	* switched-off source could answer perfectly well; the operator decided it
+	* should not. Folding the choice in is how `disabled` and `broken` stop being
+	* distinguishable, which is the D62 rule this repo has already paid for twice:
+	* an off switch is REPORTED off (`CameraStatus.switchedOff`, the same word),
+	* and disabled must never look like broken. It is also what lets every
+	* exhaustive consumer of the availability enum keep compiling.
+	*
+	* A switched-off source contributes NO clips (`listClips` never calls it) and
+	* its row carries no `catalogAsOf`: nothing confirms a catalog it is not
+	* allowed to serve, and a frozen age that can only grow draws a stalling
+	* source rather than an off switch.
+	*
+	* The row survives BECAUSE it is the control the operator switches the source
+	* back on from — D554 decision 4's rule ("a source that cannot answer
+	* produces a ROW, not an absence") applied to the one case D556 carved out of
+	* it, and D557's own kept property ("a source is never hidden, only its
+	* rows"). Absent means on.
+	*
+	* A provider never sets this — like {@link ClipSourceSchema.addonId} it is
+	* stamped by the collection dispatcher, which holds the registry's projection
+	* of the persisted authority (D556) and is the only place that knows it.
+	*/
+	switchedOff: zod.z.boolean().optional()
+});
 var videoclipsCapability = {
 	name: "videoclips",
 	scope: "device",
-	mode: "singleton",
+	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.
+	*
+	* `topTab` because the browser owns the whole pane (a day's clips, a source
+	* list and a player), exactly as `ptz` does; the widget itself is
+	* `host/clips-browser` in ui-library's `HOST_WIDGETS`.
+	*/
+	deviceConfig: { ui: {
+		kind: "widget",
+		widgetId: "host/clips-browser",
+		tab: "clips",
+		topTab: true,
+		label: "Clips",
+		order: 0
+	} },
 	methods: {
 		listClips: method(zod.z.object({
 			deviceId: zod.z.number(),
 			since: zod.z.number(),
 			until: zod.z.number(),
-			limit: zod.z.number().int().positive().optional()
+			limit: zod.z.number().int().positive().optional(),
+			/**
+			* View filter over {@link ClipSourceSchema.source} values — the
+			* picker's selection, forwarded so a provider need not list what
+			* nobody is looking at. ABSENT means every source this camera has,
+			* which is the honest default for a surface whose whole point is that
+			* nothing is hidden (D554 3). A provider with one source ignores it.
+			*/
+			sources: zod.z.array(zod.z.string()).optional()
 		}), zod.z.array(ClipSchema).readonly(), {
 			kind: "query",
-			auth: "admin"
+			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(zod.z.object({ deviceId: zod.z.number() }), zod.z.array(ClipSourceSchema).readonly(), {
+			kind: "query",
+			auth: "protected"
 		}),
 		getClipPlayback: method(zod.z.object({
 			deviceId: zod.z.number(),
-			clipId: zod.z.string()
+			clipId: zod.z.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: "admin"
+			auth: "protected"
 		})
 	}
 };
@@ -45989,6 +46297,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"videoclips.listSources": {
+		capName: "videoclips",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"viewerUi.getStaticDir": {
 		capName: "viewer-ui",
 		capScope: "system",
@@ -47997,6 +48311,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"videoclips.listSources": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"waterHeater.setAway": [{
 		name: "deviceId",
 		form: "single",
@@ -49779,6 +50098,12 @@ Object.defineProperty(exports, "objectInputDeclaresAddonId", {
 		return objectInputDeclaresAddonId;
 	}
 });
+Object.defineProperty(exports, "objectInputDeclaresRequiredDeviceId", {
+	enumerable: true,
+	get: function() {
+		return objectInputDeclaresRequiredDeviceId;
+	}
+});
 Object.defineProperty(exports, "parseJsonObject", {
 	enumerable: true,
 	get: function() {

package/dist/index.d.ts

@@ -16,6 +16,13 @@ export { AlertCenterAddon } from './builtins/alerts/index.js';
 export { ConsoleDestination, ConsoleLoggingAddon } from './builtins/console-logging/index.js';
 export { CoreBlocksAddon } from './builtins/core-blocks/index.js';
 export { DeviceManagerAddon } from './builtins/device-manager/index.js';
+/**
+ * The per-device wrapper activation (D556). Exported because it is the
+ * OPERATOR-FACING verb and the only writer of the registry's per-device source
+ * projection — a spec that proves "activate, then list" must be able to drive
+ * the real one, not a re-implementation of it.
+ */
+export { isSourceDenied, nextDisabledSources, restoreDeviceSourceActivations, setWrapperActive, type WrapperActivationDeps, type WrapperActivationInput, } from './builtins/device-manager/device-source-activation.js';
 export { HubForwarderAddon, HubForwarderDestination } from './builtins/hub-forwarder/index.js';
 export { LivenessMonitorAddon } from './builtins/liveness-monitor/index.js';
 export { LocalAuthAddon } from './builtins/local-auth/index.js';