@camstack/system 1.2.231 → 1.2.233

package/dist/snapshot-courtesy-oeTWCXPv.js

@@ -0,0 +1,165 @@
+const require_chunk = require("./chunk-Cek0wNdY.js");
+let sharp = require("sharp");
+sharp = require_chunk.__toESM(sharp);
+//#region src/builtins/snapshot/snapshot-courtesy.ts
+/**
+* State treatment for a camera that cannot produce a current frame.
+*
+* ── Why this exists ───────────────────────────────────────────────────────
+* A disabled, offline or sleeping camera has no frame, and until 2026-08-11 the
+* snapshot service simply had nothing to say about it: the media route answered
+* **404** and the client painted "Unavailable". Measured on the live grid that
+* day, 10 of 26 tiles were 404s — one genuinely disabled camera plus nine dead
+* legacy rows. A 404 is indistinguishable from a broken camera, so an operator
+* who deliberately switched a camera off saw the same thing as a fault ([D62]:
+* "an off switch is REPORTED off; disabled must never look like broken").
+*
+* So the service answers with an image that SAYS what is going on, carrying
+* the camera's own name. When a real cached frame exists it remains visible
+* under the treatment; otherwise the generated courtesy background is used.
+*
+* ── Why sharp and not ffmpeg ──────────────────────────────────────────────
+* The first draft of this file shelled out to `ffmpeg` with a `drawtext`
+* filter. That was written before the resize path was measured, and it was the
+* wrong call for the same reason: this runs in the snapshot wrapper, a system
+* builtin loaded in the hub's ROOT process, so every render was a fork + exec
+* on the loop that serves the API — 52 ms against sharp's 4.8 ms in that
+* container, to draw two lines of text.
+*
+* `terminal-frame-renderer.ts` already renders text this way (SVG → sharp), so
+* this is the house pattern rather than a new one. It also drops the font-PATH
+* probing the ffmpeg version needed: an SVG names a font FAMILY and fontconfig
+* resolves it — verified in the hub image, where `fc-match "DejaVu Sans Mono"`
+* answers with the real file.
+*
+* Rendering is pure input → bytes with no I/O of its own, and the geometry and
+* escaping are separated out so they stay testable without rasterizing.
+*/
+/** Default tile size when the caller asks for no particular width. */
+var COURTESY_DEFAULT_WIDTH = 640;
+/**
+* Font stack for the rendered text. Family names, not paths — librsvg resolves
+* them through fontconfig, and the trailing generics keep a host without DejaVu
+* rendering something legible instead of nothing.
+*/
+var COURTESY_FONT_STACK = "DejaVu Sans,DejaVu Sans Mono,Helvetica,Arial,sans-serif";
+/** The word the frame carries. Deliberately the operator's vocabulary. */
+function courtesyLabel(reason) {
+	switch (reason) {
+		case "disabled": return "Disabled";
+		case "offline": return "Offline";
+		case "sleeping": return "Sleeping";
+		case "unreachable": return "Unreachable";
+		case "waking": return "Waking";
+	}
+}
+/**
+* Background per reason. A disabled camera is a DELIBERATE state and must not
+* read as an alarm, so it is neutral grey; offline is a fault and is warmer.
+*/
+function courtesyBackground(reason) {
+	switch (reason) {
+		case "disabled": return "#2b2b31";
+		case "offline": return "#3a2b2b";
+		case "sleeping": return "#232b3a";
+		case "waking": return "#243247";
+		case "unreachable": return "#3a2b2b";
+	}
+}
+/** XML escaping for text placed inside an SVG `<text>` node. */
+function escapeCourtesyText(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
+}
+/**
+* The SVG the frame is rasterized from: the state large and centred, the
+* camera's name under it, smaller and dimmer.
+*
+* Sizes derive from the width so a 240 px grid tile and a 1920 px full-bleed
+* frame read the same, with a floor so a thumbnail stays legible.
+*/
+function buildCourtesySvg(spec) {
+	return buildStateSvg(spec, false);
+}
+/**
+* The same state treatment as a courtesy frame, but translucent so the last
+* real camera frame remains visible underneath it.
+*/
+function buildCourtesyOverlaySvg(spec) {
+	return buildStateSvg(spec, true);
+}
+function buildStateSvg(spec, overlay) {
+	const stateSize = Math.max(12, Math.round(spec.width / 12));
+	const nameSize = Math.max(9, Math.round(spec.width / 26));
+	const state = escapeCourtesyText(courtesyLabel(spec.reason));
+	const name = escapeCourtesyText(spec.deviceName);
+	const midY = spec.height / 2;
+	const washOpacity = overlay ? "0.62" : "1";
+	const textStroke = Math.max(1, Math.round(spec.width / 320));
+	return [
+		`<svg xmlns="http://www.w3.org/2000/svg" width="${String(spec.width)}" height="${String(spec.height)}">`,
+		`<rect width="100%" height="100%" fill="${courtesyBackground(spec.reason)}" fill-opacity="${washOpacity}"/>`,
+		`<g font-family="${COURTESY_FONT_STACK}" text-anchor="middle" paint-order="stroke" stroke="#111118" stroke-width="${String(textStroke)}">`,
+		`<text x="50%" y="${String(Math.round(midY))}" font-size="${String(stateSize)}" fill="#e8e8ee">${state}</text>`,
+		`<text x="50%" y="${String(Math.round(midY + stateSize))}" font-size="${String(nameSize)}" fill="#9a9aa8">${name}</text>`,
+		`</g></svg>`
+	].join("");
+}
+/** Cache key — a courtesy frame is a pure function of these four. */
+function courtesyCacheKey(spec) {
+	return `${spec.reason}:${String(spec.width)}x${String(spec.height)}:${spec.deviceName}`;
+}
+/**
+* Render the frame.
+*
+* Rejects on failure — the caller decides what to do, exactly as `resizeJpeg`
+* does, so a broken courtesy path is never mistaken for a broken camera.
+*/
+function renderCourtesyJpeg(spec) {
+	return (0, sharp.default)(Buffer.from(buildCourtesySvg(spec))).jpeg({ quality: 82 }).toBuffer().then((bytes) => {
+		if (bytes.length === 0) throw new Error("courtesy frame produced no bytes");
+		return bytes;
+	});
+}
+/**
+* Paint the state treatment over a real cached frame.
+*
+* The source dimensions are authoritative: overlays preserve the original
+* frame rather than resizing it to the generated courtesy-frame default.
+*/
+async function renderCourtesyOverlayJpeg(background, spec) {
+	const metadata = await (0, sharp.default)(background).metadata();
+	if (!metadata.width || !metadata.height) throw new Error("cached snapshot has no renderable dimensions");
+	const overlay = Buffer.from(buildCourtesyOverlaySvg({
+		...spec,
+		width: metadata.width,
+		height: metadata.height
+	}));
+	const bytes = await (0, sharp.default)(background).composite([{ input: overlay }]).jpeg({ quality: 82 }).toBuffer();
+	if (bytes.length === 0) throw new Error("courtesy overlay produced no bytes");
+	return bytes;
+}
+//#endregion
+Object.defineProperty(exports, "COURTESY_DEFAULT_WIDTH", {
+	enumerable: true,
+	get: function() {
+		return COURTESY_DEFAULT_WIDTH;
+	}
+});
+Object.defineProperty(exports, "courtesyCacheKey", {
+	enumerable: true,
+	get: function() {
+		return courtesyCacheKey;
+	}
+});
+Object.defineProperty(exports, "renderCourtesyJpeg", {
+	enumerable: true,
+	get: function() {
+		return renderCourtesyJpeg;
+	}
+});
+Object.defineProperty(exports, "renderCourtesyOverlayJpeg", {
+	enumerable: true,
+	get: function() {
+		return renderCourtesyOverlayJpeg;
+	}
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.231",
+  "version": "1.2.233",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",