@camstack/addon-terminal 0.1.21 → 0.1.23

package/dist/addon.js

@@ -19493,6 +19493,39 @@ var snapshotCapability = {
 			etag: string().nullable()
 		}))),
 		/**
+		* The full decision chain for ONE device, for the viewer's debug readout —
+		* the answer to "why does this tile show what it shows" in a single poll:
+		* the battery slice the state was derived from, the resolved state + its
+		* reason, the cached frame's identity/age, whether a wake window is open,
+		* and whether a fresh capture is in flight. Cache-only and capture-free:
+		* a debug read must never wake a battery camera.
+		*/
+		getDebugState: systemMethod(object({ deviceId: number() }), object({
+			/** The battery slice as read, or null when the device has none. */
+			battery: object({
+				sleeping: boolean(),
+				lastUpdated: number(),
+				lastContactAt: number().optional()
+			}).nullable(),
+			/** The resolved snapshot state (what the overlay decision used). */
+			state: object({
+				isBattery: boolean(),
+				reason: _enum([
+					"disabled",
+					"sleeping",
+					"unreachable",
+					"waking"
+				]).nullable()
+			}),
+			/** The cached frame behind the next paint. */
+			frame: object({
+				capturedAt: number().nullable(),
+				ageMs: number().nullable()
+			}),
+			/** A wake window is currently open (the Waking overlay's source). */
+			waking: boolean()
+		})),
+		/**
 		* Signed, expiring links to a CLIENT-SIZED frame — and the demand signal
 		* that makes those frames current.
 		*
@@ -19574,7 +19607,14 @@ targets: array(object({
 				"sleeping",
 				"unreachable",
 				"waking"
-			]).nullable()
+			]).nullable(),
+			/** A battery camera (whatever its current state). An AWAKE battery
+			*  camera is deliberately NOT recaptured on the poll cadence — every
+			*  capture is a camera hit that would keep it out of sleep — so its
+			*  cached frame legitimately ages past the currency ceiling while
+			*  nothing is streaming. A surface must keep painting it (a fresh
+			*  frame is captured at each wake), not blank to "unavailable". */
+			battery: boolean()
 		})))
 	},
 	status: {
@@ -34154,6 +34194,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"snapshot.getDebugState": {
+		capName: "snapshot",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"snapshot.getSnapshot": {
 		capName: "snapshot",
 		capScope: "device",
@@ -36751,6 +36797,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"snapshot.getDebugState": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"snapshot.getSnapshot": [{
 		name: "deviceId",
 		form: "single",

package/dist/addon.mjs

@@ -19470,6 +19470,39 @@ var snapshotCapability = {
 			etag: string().nullable()
 		}))),
 		/**
+		* The full decision chain for ONE device, for the viewer's debug readout —
+		* the answer to "why does this tile show what it shows" in a single poll:
+		* the battery slice the state was derived from, the resolved state + its
+		* reason, the cached frame's identity/age, whether a wake window is open,
+		* and whether a fresh capture is in flight. Cache-only and capture-free:
+		* a debug read must never wake a battery camera.
+		*/
+		getDebugState: systemMethod(object({ deviceId: number() }), object({
+			/** The battery slice as read, or null when the device has none. */
+			battery: object({
+				sleeping: boolean(),
+				lastUpdated: number(),
+				lastContactAt: number().optional()
+			}).nullable(),
+			/** The resolved snapshot state (what the overlay decision used). */
+			state: object({
+				isBattery: boolean(),
+				reason: _enum([
+					"disabled",
+					"sleeping",
+					"unreachable",
+					"waking"
+				]).nullable()
+			}),
+			/** The cached frame behind the next paint. */
+			frame: object({
+				capturedAt: number().nullable(),
+				ageMs: number().nullable()
+			}),
+			/** A wake window is currently open (the Waking overlay's source). */
+			waking: boolean()
+		})),
+		/**
 		* Signed, expiring links to a CLIENT-SIZED frame — and the demand signal
 		* that makes those frames current.
 		*
@@ -19551,7 +19584,14 @@ targets: array(object({
 				"sleeping",
 				"unreachable",
 				"waking"
-			]).nullable()
+			]).nullable(),
+			/** A battery camera (whatever its current state). An AWAKE battery
+			*  camera is deliberately NOT recaptured on the poll cadence — every
+			*  capture is a camera hit that would keep it out of sleep — so its
+			*  cached frame legitimately ages past the currency ceiling while
+			*  nothing is streaming. A surface must keep painting it (a fresh
+			*  frame is captured at each wake), not blank to "unavailable". */
+			battery: boolean()
 		})))
 	},
 	status: {
@@ -34131,6 +34171,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"snapshot.getDebugState": {
+		capName: "snapshot",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"snapshot.getSnapshot": {
 		capName: "snapshot",
 		capScope: "device",
@@ -36728,6 +36774,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"snapshot.getDebugState": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"snapshot.getSnapshot": [{
 		name: "deviceId",
 		form: "single",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-terminal",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Interactive terminal sessions (pty + xterm) as a CamStack addon",
   "keywords": [
     "camstack",