@camstack/addon-osd-manager 0.1.123 → 0.1.124

package/dist/index.js

@@ -5363,7 +5363,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#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).
@@ -5563,6 +5563,12 @@ Object.fromEntries([
 		icon: "circle-dot",
 		order: 40
 	},
+	{
+		id: "clips",
+		label: "Clips",
+		icon: "clapperboard",
+		order: 41
+	},
 	{
 		id: "engine",
 		label: "Inference Engine",
@@ -15940,14 +15946,30 @@ var deviceManagerCapability = {
 		*/
 		getAllBindings: method(object({}), 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(object({
 			deviceId: number(),
 			capName: string(),
 			wrapperAddonId: string(),
+			/** The `ClipSource.source` id to toggle. Absent = all of the addon's. */
+			sourceId: string().optional(),
 			active: boolean()
 		}), _void(), {
 			kind: "mutation",
@@ -27109,10 +27131,9 @@ var ServerBootModeSchema = _enum([
 *  - `idle` / `checking` / `staging` — steady / in-flight registry work.
 *  - `pending-restart` — a version is staged and the node has NOT yet
 *    restarted onto it (still running the OLD version).
-*  - `awaiting-confirmation` — the node HAS restarted onto the staged version
-*    (it is the active probation boot) and is waiting to confirm boot-health.
-*    Apply/rollback are refused in this state and the node must NOT be
-*    manually restarted, or the probation boot auto-rolls-back.
+*  - `awaiting-confirmation` — RETIRED with the probation boot (single-copy
+*    collapse, 2026-07-18). Kept in the enum so an older client still parses;
+*    no provider emits it.
 */
 var ServerUpdateStateSchema = _enum([
 	"idle",
@@ -27201,12 +27222,35 @@ var ServerRollbackInfoSchema = object({
 var ServerPackageStatusSchema = object({
 	/** Root package name (`@camstack/server` on the hub). */
 	packageName: string(),
-	/** Version of the code the running process ACTUALLY loaded. */
+	/**
+	* Version of the code THIS PROCESS loaded — captured once, at boot, from the
+	* package.json of the copy the code was loaded from, and never re-read. A
+	* copy replaced on disk under a live process must not move this number;
+	* that divergence is what `installedVersion` is for. Before 2026-09-20 this
+	* was a lazy disk read that would have followed such a swap silently.
+	*/
 	runningVersion: string().nullable(),
 	/** Node.js runtime version the node's process runs on (`process.versions.node`). */
 	nodeRuntimeVersion: string().nullable(),
 	/** Active data-dir root version; null when booted from seed/workspace. */
 	activeVersion: string().nullable(),
+	/**
+	* Version of the root package in the data-root `current/` copy RIGHT NOW —
+	* what the next boot would load if nothing is staged. Normally equal to
+	* `runningVersion`; differs only when the copy on disk changed under the
+	* live process. `null` when there is no data-root copy (baked seed or
+	* workspace boot). Optional for version skew: an older provider omits it.
+	*/
+	installedVersion: string().nullable().optional(),
+	/**
+	* True when the code that would run after a restart is NOT the code running
+	* now: a version is staged (`pendingVersion`), or `installedVersion` differs
+	* from `runningVersion`. Derived on every read, never stored. This is the
+	* one field that lets an operator or a script say "1.2.353 is installed and
+	* will run after a restart" instead of reading it off a number that means
+	* "installed". Optional for version skew.
+	*/
+	restartRequired: boolean().optional(),
 	/** N-1 version kept for rollback; null when no previous version exists. */
 	previousVersion: string().nullable(),
 	/** Version of the immutable baked seed closure (image fallback). */
@@ -27241,19 +27285,71 @@ var ServerPackageStatusSchema = object({
 });
 var ServerUpdateCheckResultSchema = object({
 	packageName: string(),
+	/** Same meaning as on the status payload: what THIS process loaded. */
 	runningVersion: string().nullable(),
 	latestVersion: string().nullable(),
+	/**
+	* `latestVersion` is newer than `runningVersion` AND is not the version
+	* already staged on this node. A staged-and-waiting version is not "an
+	* update available" — applying it again is refused (`already-staged`), and
+	* a button that announced "updating…" on this boolean then got refused
+	* would be lying. It is reported through `pendingVersion` instead.
+	*/
 	updateAvailable: boolean(),
 	checkedAtMs: number(),
 	/** Non-null when the registry lookup failed (offline, bad registry, …). */
-	error: string().nullable()
+	error: string().nullable(),
+	/**
+	* Version staged on this node and awaiting its restart, when one is. Before
+	* 2026-09-20 a check answered `{runningVersion, updateAvailable:false}` for a
+	* node whose staged closure had never booted, and the caller had no way to
+	* see the difference. Optional for version skew.
+	*/
+	pendingVersion: string().nullable().optional(),
+	/** See the status payload: staged, or installed-on-disk ≠ running. Optional for skew. */
+	restartRequired: boolean().optional()
 });
+/**
+* What an action DID — the discriminant `accepted` cannot carry. Before
+* 2026-09-20 `applyServerUpdate` answered `accepted:false` both for a refusal
+* where nothing was wrong (already current, already staged) and for a staging
+* install that died on `npm error code ECONNRESET`; the only difference was
+* prose in `message`, and an operator restarted a container on the strength of
+* it, booting the previous version.
+*
+*  - `staged`            — the closure is installed and validated; the node
+*                          restarts to apply it (`restarting:true`). NOTHING
+*                          runs the new code until that restart completes.
+*  - `restart-scheduled` — a plain, version-preserving restart was accepted.
+*  - `already-current`   — the target IS the running version; nothing done.
+*  - `refused`           — dropped by a gate; `reason` names which.
+*  - `failed`            — attempted and did not land; `error` says why.
+*/
+var ServerUpdateOutcomeSchema = _enum([
+	"staged",
+	"restart-scheduled",
+	"already-current",
+	"refused",
+	"failed"
+]);
 var ServerUpdateActionResultSchema = object({
 	accepted: boolean(),
 	targetVersion: string().nullable(),
 	/** True when a graceful restart was scheduled to apply the change. */
 	restarting: boolean(),
-	message: string()
+	message: string(),
+	/** See {@link ServerUpdateOutcomeSchema}. Optional for version skew. */
+	outcome: ServerUpdateOutcomeSchema.optional(),
+	/**
+	* Stable, greppable cause for `refused` / `failed` (the engine's
+	* `UpdateRefusalReason`, `staging-failed`, …). `null` on success.
+	*/
+	reason: string().nullable().optional(),
+	/**
+	* The failure itself, verbatim enough to act on (the npm output for a
+	* staging install). Non-null only for `failed`.
+	*/
+	error: string().nullable().optional()
 });
 var serverManagementCapability = {
 	name: "server-management",
@@ -28944,41 +29040,299 @@ 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()
 });
 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()
 });
+/**
+* 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 = 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: `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: 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: 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: 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(object({
 			deviceId: number(),
 			since: number(),
 			until: number(),
-			limit: number().int().positive().optional()
+			limit: 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: array(string()).optional()
 		}), 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(object({ deviceId: number() }), array(ClipSourceSchema).readonly(), {
+			kind: "query",
+			auth: "protected"
 		}),
 		getClipPlayback: method(object({
 			deviceId: number(),
-			clipId: string()
+			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: "admin"
+			auth: "protected"
 		})
 	}
 };
@@ -47072,6 +47426,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"videoclips.listSources": {
+		capName: "videoclips",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"viewerUi.getStaticDir": {
 		capName: "viewer-ui",
 		capScope: "system",
@@ -49080,6 +49440,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"videoclips.listSources": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"waterHeater.setAway": [{
 		name: "deviceId",
 		form: "single",