@camstack/addon-terminal 0.1.13 → 0.1.16

package/dist/addon.mjs

@@ -1,6 +1,8 @@
 import { createRequire } from "node:module";
+import { execFile } from "node:child_process";
 import { accessSync, chmodSync, constants, existsSync, statSync } from "node:fs";
-import { delimiter, dirname, join } from "node:path";
+import path, { delimiter, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import sharp from "sharp";
 import { createServer } from "node:http";
 //#region \0rolldown/runtime.js
@@ -7022,6 +7024,18 @@ method(object({ deviceId: number() }), array(StreamSourceEntrySchema)), method(o
 	action: string().min(1),
 	input: unknown()
 }), unknown(), { kind: "mutation" }), method(object({ deviceId: number() }), _void(), { kind: "mutation" }), method(object({ deviceId: number() }), unknown().nullable()), method(object({ deviceId: number() }), RawStateResultSchema.nullable(), { auth: "protected" });
+//#endregion
+//#region ../types/dist/err-msg-IQTHeDzc.mjs
+/**
+import { errMsg } from '@camstack/types'
+* Extract a human-readable message from an unknown error value.
+* Replaces the ubiquitous `errMsg(err)` pattern.
+*/
+function errMsg(err) {
+	if (err instanceof Error) return err.message;
+	if (typeof err === "string") return err;
+	return String(err);
+}
 var EncodeProfileSchema = object({
 	video: object({
 		codec: _enum([
@@ -7259,8 +7273,31 @@ var AdoptionJobSchema = object({
 	error: string().nullable()
 });
 /**
-* Per-camera FUNCTION SWITCHES — the one coherent on/off surface over the
-* pipeline functions an operator thinks in terms of.
+* Per-camera FUNCTION SWITCHES.
+*
+* ## The aggregate group is being withdrawn — the BADGE is not (D113)
+*
+* This file shipped as "the one coherent on/off surface over the pipeline
+* functions an operator thinks in terms of". The operator's verdict on
+* 2026-08-12 was that the coherent surface bought complexity and no clarity:
+* every function already had a settings page of its own, and a second place to
+* turn it off is a second place to look. Each switch is going back to its own
+* component's original options — detection to the detection-pipeline wrapper
+* binding, audio analysis to its own, recording to `RecordingConfig.enabled`
+* (which was always first-class; the switch was a veneer over
+* `recording.setDeviceConfig`), notifications to a notification-center
+* per-device setting, the two camera planes to their own components.
+*
+* What survives is {@link composeSwitchedOff}: `CameraStatus.switchedOff`, the
+* thing that lets a status surface say DISABLED instead of BROKEN, recomposed
+* straight from the authorities with no group in the middle. That rule was
+* never about a control panel.
+*
+* Everything else here — {@link CAMERA_SWITCH_CATALOG}, {@link CameraSwitch},
+* {@link deriveCameraSwitches}, the `pipelineOrchestrator.getCameraSwitches` /
+* `setCameraSwitch` pair — is a COMPATIBILITY surface for as long as deployed
+* viewers (v1.0.305) and the admin UI still call it. It is deleted when they
+* stop; nothing new may be built on it.
 *
 * ## This file adds no state
 *
@@ -7422,6 +7459,14 @@ var CameraSwitchGroupSchema = object({
 	fetchedAt: number()
 });
 /**
+* The wrapper capability each wrapper-backed switch controls. Named constants
+* because the same strings appear in `legacy-migrations.ts`, in
+* `isCapActiveForDevice` call sites and in the fake harness — a typo in any of
+* them is a switch that silently writes a binding nobody reads.
+*/
+var DETECTION_PIPELINE_CAP_NAME = "detection-pipeline";
+var AUDIO_ANALYSIS_CAP_NAME = "audio-analysis";
+/**
 * Ops-log — the durable, append-only operations audit shared by the
 * recordings and events management surfaces.
 *
@@ -17797,9 +17842,16 @@ var CameraStatusSchema = object({
 	audio: CameraAudioStatusSchema.nullable(),
 	recording: CameraRecordingStatusSchema.nullable(),
 	/**
-	* Per-camera function switches an OPERATOR has turned off
+	* Per-camera functions an OPERATOR has turned off
 	* ([D61](../../../../docs/decisions/adr-0067.md)).
 	*
+	* Composed from the AUTHORITIES themselves — the wrapper bindings,
+	* `RecordingConfig.enabled`, the notification mute, the broker's audio
+	* policy, the camera's own microphone — via `composeSwitchedOff`, not from
+	* the deprecated `getCameraSwitches` group ([D113](../../../../docs/decisions/adr-0113.md)).
+	* The badge outlives the control panel: the panel was a convenience, this is
+	* the difference between a camera being off and a camera being dead.
+	*
 	* This is the difference between DISABLED and BROKEN. A camera whose
 	* `detection` block reports zero fps and whose `switchedOff` contains
 	* `'object-detection'` was switched off by a person; the same camera with an
@@ -24886,10 +24938,42 @@ method(object({
 */
 /** Playback-speed multiplier for the render (1 = realtime). */
 var ExportSpeedSchema = number().min(.25).max(32);
+/**
+* One dense interval, in SECONDS FROM THE EXPORT'S OWN `fromMs`.
+*
+* Relative and not absolute epoch on purpose: the renderer's frame-select
+* expression sees ffmpeg's `t`, which starts at 0 for the export's source
+* playlist. Handing it absolute epochs would make every call site responsible
+* for the same subtraction, and the one that forgot would emit a filter that
+* selects nothing — silently, as a uniform timelapse.
+*/
+var ExportDenseRangeSchema = object({
+	fromSec: number().nonnegative(),
+	toSec: number().nonnegative()
+}).refine((r) => r.toSec > r.fromSec, { message: "dense range must have toSec > fromSec" });
+/**
+* Dense-interval overlay for a timelapse: sample at `dense.everyMs` INSIDE the
+* listed ranges and at the base `everyMs` everywhere else.
+*
+* `everyMs` must be strictly smaller than the base cadence — a dense rate that
+* is not denser renders a uniform timelapse the operator believes is two-rate.
+*/
+var ExportDenseSchema = object({
+	everyMs: number().int().positive(),
+	ranges: array(ExportDenseRangeSchema).min(1).max(200)
+});
 /** Timelapse cadence — sample one source frame per `everyMs`, output at `outputFps`. */
 var ExportTimelapseSchema = object({
 	everyMs: number().int().positive(),
-	outputFps: number().int().min(1).max(60).optional()
+	outputFps: number().int().min(1).max(60).optional(),
+	/** Optional second, FASTER rate over the intervals that matter. */
+	dense: ExportDenseSchema.optional()
+}).superRefine((v, ctx) => {
+	if (v.dense !== void 0 && v.dense.everyMs >= v.everyMs) ctx.addIssue({
+		code: ZodIssueCode.custom,
+		message: "dense.everyMs must be strictly smaller than the base everyMs",
+		path: ["dense", "everyMs"]
+	});
 });
 /**
 * Render options. `speed` and `timelapse` are mutually exclusive. `includeAudio`
@@ -24947,6 +25031,19 @@ var ExportDownloadSchema = object({
 	url: string(),
 	endpoints: array(string())
 });
+/**
+* A finished export's bytes, inline.
+*
+* `bytes` is the DECODED length — the number the caller bounds and logs
+* against, so nobody has to infer it from the base64 length.
+*/
+var ExportBytesSchema = object({
+	base64: string(),
+	contentType: string(),
+	/** Suggested filename, extension included. */
+	name: string(),
+	bytes: number().int().nonnegative()
+});
 method(object({
 	deviceId: number(),
 	profile: string(),
@@ -24971,6 +25068,9 @@ method(object({
 }), method(object({ exportId: string() }), ExportDownloadSchema, {
 	kind: "query",
 	auth: "protected"
+}), method(object({ exportId: string() }), ExportBytesSchema, {
+	kind: "query",
+	auth: "protected"
 });
 /**
 * scene-monitor — device-scoped reference-region state cap. An operator marks
@@ -31822,6 +31922,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"recordingExport.readExportBytes": {
+		capName: "recordingExport",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"sceneMonitor.captureReference": {
 		capName: "scene-monitor",
 		capScope: "device",
@@ -33239,10 +33345,28 @@ TimelapseRuleInputSchema.extend({
 	*/
 	ownerUserId: string().optional(),
 	/**
-	* Epoch-ms of the last successful generation — the 1-hour re-generation
-	* guard's durable state (predecessor parity). Absent = never generated.
+	* Epoch-ms of the NEWEST successful generation across every camera of this
+	* rule. What a UI shows, and the compatibility floor for
+	* {@link readTimelapseGeneratedAt}. Absent = never generated.
 	*/
 	lastGeneratedAt: number().optional(),
+	/**
+	* PER-CAMERA generation state, keyed by `String(deviceId)` — the
+	* re-generation guard's real durable state.
+	*
+	* One rule covers several cameras and each renders its own video, so a rule
+	* -wide stamp is wrong in the direction that DESTROYS work: camera A
+	* succeeding at 06:05 tells camera B, whose render failed, that it is
+	* already done — and B's night is gone for good, because the window will not
+	* come back.
+	*
+	* ADDITIVE, so the migration is free: a row written before this field simply
+	* has no map, and {@link readTimelapseGeneratedAt} falls back to
+	* {@link TimelapseRuleSchema.shape.lastGeneratedAt}. Reading an old row as
+	* "never generated" would re-render and re-notify every camera of every rule
+	* once, on the deploy that shipped the map.
+	*/
+	generatedByDevice: record(string(), number()).optional(),
 	/** userId of the caller who created the rule (server-stamped). */
 	createdBy: string(),
 	createdAt: number(),
@@ -33355,6 +33479,46 @@ DEFAULT_NATIVE_LEASE_SETTINGS.budgetMb;
 DEFAULT_NATIVE_LEASE_SETTINGS.activityMs;
 DEFAULT_NATIVE_LEASE_SETTINGS.admission;
 //#endregion
+//#region src/curses-shim.ts
+/**
+* macOS repair for the managed Python's curses.
+*
+* The python-build-standalone distribution the dependency resolver installs on
+* macOS links ncurses statically with the terminfo database compiled OUT
+* (`--disable-database`) and an ABI mismatch that misparses every numeric
+* capability of its five built-in fallback terminals (`colors=-1`,
+* `cols=524368`). `has_colors()` is therefore False under every TERM value and
+* `init_pair` is hard-blocked, so glances takes its B&W branch and paints the
+* whole screen with SGR conceal/reverse/alt-charset — the "text missing,
+* light bars instead" terminal camera frames. No environment variable can fix
+* it: the code that would read TERMINFO/TERMINFO_DIRS was never compiled in.
+*
+* The repair ships prebuilt `_curses` / `_curses_panel` extension modules
+* linked against the system `/usr/lib/libncurses.5.4.dylib` (universal2) and
+* puts their directory on PYTHONPATH at PTY spawn — PYTHONPATH precedes
+* lib-dynload on sys.path, so the working modules shadow the broken ones with
+* no change to the managed distribution. The filename is ABI-locked to
+* cpython-312: a managed-python bump to 3.13 makes the shim silently inert
+* (python ignores a mismatched ABI tag), which is why the addon probes
+* `tigetnum("colors")` at startup and logs loudly when colours are missing.
+*/
+/** `<addonRoot>/assets/curses-shim/py312`, valid from both src/ and dist/. */
+function cursesShimDir() {
+	return path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "assets", "curses-shim", "py312");
+}
+function cursesShimDirExists(shimDir) {
+	return existsSync(shimDir);
+}
+/**
+* The env to merge into the glances profile, or undefined when the shim does
+* not apply (non-macOS, or the assets were not shipped).
+*/
+function resolveGlancesCursesShimEnv(options) {
+	if (options.platform !== "darwin" || !options.shimDirExists) return void 0;
+	const existing = options.existingPythonPath?.trim();
+	return { PYTHONPATH: existing ? `${options.shimDir}:${existing}` : options.shimDir };
+}
+//#endregion
 //#region src/pty.ts
 /**
 * Minimal pty abstraction. The manager depends on this interface, never on
@@ -33451,6 +33615,91 @@ async function warmNodePty() {
 	await loadNodePty();
 }
 //#endregion
+//#region src/silence-analysis.ts
+/**
+* Every analyzer a Terminal camera is created with switched OFF.
+*
+* `motion-detection` sits first deliberately: it is the one that holds the
+* decode session open, so it is the one whose absence is the difference between
+* a terminal costing a screen scrape and costing a decode pipeline.
+*/
+var TERMINAL_SILENCED_CAP_NAMES = [
+	"motion-detection",
+	DETECTION_PIPELINE_CAP_NAME,
+	AUDIO_ANALYSIS_CAP_NAME
+];
+/**
+* Resolve the addon currently providing `capName` for this device.
+*
+* Inlined rather than reached for through a helper because there is exactly one
+* honest source: the device's own bindings. `listBindableCapsForDeviceType`
+* answers for the device TYPE and would happily name a wrapper that is not the
+* one bound here.
+*
+* Returns `null` when the cap is not bound at all — which is not an error: a
+* deployment with no audio analyzer has nothing to switch off, and demanding one
+* would make every terminal creation fail on a perfectly valid hub.
+*/
+async function resolveBoundWrapper(api, deviceId, capName) {
+	const bindings = await api.deviceManager.getBindings.query({ deviceId });
+	for (const entry of bindings.entries) {
+		if (entry.capName !== capName) continue;
+		if (entry.kind !== "wrapped") continue;
+		if (entry.providerAddonId === "") return null;
+		return entry.providerAddonId;
+	}
+	return null;
+}
+/**
+* Switch every analyzer in {@link TERMINAL_SILENCED_CAP_NAMES} off for one
+* Terminal camera.
+*
+* Called ONLY on creation. An operator who deliberately turns detection back on
+* for a terminal must win, and a reconcile that re-asserted every pass would
+* silently overrule them once a minute.
+*
+* @throws if a cap IS bound and the write to its authority failed. The camera
+* would then be running a full analyzer for a screen recording, which is the
+* exact cost this exists to remove — and a silent version of that failure is
+* unfindable.
+*/
+async function silenceAnalysisFor(deps, deviceId) {
+	const failures = [];
+	for (const capName of TERMINAL_SILENCED_CAP_NAMES) try {
+		const wrapperAddonId = await resolveBoundWrapper(deps.api, deviceId, capName);
+		if (wrapperAddonId === null) {
+			deps.logger.debug("terminal camera: no analyzer bound for this capability", {
+				tags: { deviceId },
+				meta: { capName }
+			});
+			continue;
+		}
+		await deps.api.deviceManager.setWrapperActive.mutate({
+			deviceId,
+			capName,
+			wrapperAddonId,
+			active: false
+		});
+		deps.logger.info("terminal camera: analyzer switched off at its authority", {
+			tags: { deviceId },
+			meta: {
+				capName,
+				wrapperAddonId
+			}
+		});
+	} catch (err) {
+		failures.push(`${capName}: ${errMsg(err)}`);
+		deps.logger.error("terminal camera: could NOT switch an analyzer off", {
+			tags: { deviceId },
+			meta: {
+				capName,
+				error: errMsg(err)
+			}
+		});
+	}
+	if (failures.length > 0) throw new Error(`terminal camera ${deviceId}: could not switch off ${failures.length} analyzer(s) — it will run at full detection cost (${failures.join("; ")})`);
+}
+//#endregion
 //#region src/terminal-camera-declarations.ts
 /**
 * Feed DeclaredDevices every live declaration plus one deterministic orphan
@@ -33485,6 +33734,198 @@ function buildTerminalInstanceCameraDeclarations(instances) {
 function needsTerminalCameraConfigMigration(persistedConfig, declaration) {
 	return persistedConfig.instanceId !== declaration.config.instanceId || persistedConfig.nodeId !== declaration.config.nodeId || persistedConfig.profileId !== declaration.config.profileId || persistedConfig.profileLabel !== declaration.config.profileLabel;
 }
+//#endregion
+//#region src/terminal-cell-runs.ts
+var TERMINAL_DEFAULT_FG = "#d7dce2";
+var TERMINAL_DEFAULT_BG = "#0b0d10";
+/**
+* The 16 ANSI colours, in a dark-theme variant chosen to sit with the existing
+* frame (`#0b0d10` ground, `#d7dce2` text) rather than the raw xterm defaults,
+* whose pure `#0000ff` blue and `#008000` green are close to unreadable on a
+* near-black background at 13px. Index 7 IS the default foreground, so plain
+* `CSI 37m` text renders identically to unstyled text.
+*/
+var TERMINAL_ANSI_PALETTE = [
+	"#282c34",
+	"#e06c75",
+	"#98c379",
+	"#e5c07b",
+	"#61afef",
+	"#c678dd",
+	"#56b6c2",
+	TERMINAL_DEFAULT_FG,
+	"#5c6370",
+	"#ef596f",
+	"#89ca78",
+	"#f0c674",
+	"#6cb6ff",
+	"#d55fde",
+	"#2bbac5",
+	"#ffffff"
+];
+/** The six levels of the xterm 6×6×6 colour cube (indices 16-231). */
+var TERMINAL_CUBE_LEVELS = [
+	0,
+	95,
+	135,
+	175,
+	215,
+	255
+];
+var TERMINAL_CUBE_FIRST = 16;
+var TERMINAL_GRAYSCALE_FIRST = 232;
+var TERMINAL_GRAYSCALE_BASE = 8;
+var TERMINAL_GRAYSCALE_STEP = 10;
+/** SGR 2 keeps the foreground legible; it must not become the background. */
+var TERMINAL_DIM_WEIGHT = .6;
+function channel(value) {
+	return Math.max(0, Math.min(255, Math.round(value))).toString(16).padStart(2, "0");
+}
+function hex(red, green, blue) {
+	return `#${channel(red)}${channel(green)}${channel(blue)}`;
+}
+function parseHex(color) {
+	return [
+		Number.parseInt(color.slice(1, 3), 16),
+		Number.parseInt(color.slice(3, 5), 16),
+		Number.parseInt(color.slice(5, 7), 16)
+	];
+}
+/** Resolve an xterm palette index (0-255) to a hex colour. */
+function terminalPaletteColor(index) {
+	const ansi = TERMINAL_ANSI_PALETTE[index];
+	if (ansi !== void 0) return ansi;
+	if (index >= TERMINAL_GRAYSCALE_FIRST) {
+		const level = TERMINAL_GRAYSCALE_BASE + (index - TERMINAL_GRAYSCALE_FIRST) * TERMINAL_GRAYSCALE_STEP;
+		return hex(level, level, level);
+	}
+	if (index >= TERMINAL_CUBE_FIRST) {
+		const offset = index - TERMINAL_CUBE_FIRST;
+		return hex(TERMINAL_CUBE_LEVELS[Math.floor(offset / 36) % 6] ?? 0, TERMINAL_CUBE_LEVELS[Math.floor(offset / 6) % 6] ?? 0, TERMINAL_CUBE_LEVELS[offset % 6] ?? 0);
+	}
+	return TERMINAL_DEFAULT_FG;
+}
+/** Resolve a 0xRRGGBB truecolor value to a hex colour. */
+function terminalRgbColor(value) {
+	return hex(value >> 16 & 255, value >> 8 & 255, value & 255);
+}
+function blend(color, toward, weight) {
+	const [red, green, blue] = parseHex(color);
+	const [targetRed, targetGreen, targetBlue] = parseHex(toward);
+	return hex(red * weight + targetRed * (1 - weight), green * weight + targetGreen * (1 - weight), blue * weight + targetBlue * (1 - weight));
+}
+function resolveForeground(cell) {
+	if (cell.isFgRGB()) return terminalRgbColor(cell.getFgColor());
+	if (cell.isFgPalette()) return terminalPaletteColor(cell.getFgColor());
+	return TERMINAL_DEFAULT_FG;
+}
+function resolveBackground(cell) {
+	if (cell.isBgRGB()) return terminalRgbColor(cell.getBgColor());
+	if (cell.isBgPalette()) return terminalPaletteColor(cell.getBgColor());
+	return TERMINAL_DEFAULT_BG;
+}
+/**
+* Resolve one cell's attributes into concrete colours.
+*
+* Inverse is applied by SWAPPING the already-resolved pair, so inverse over two
+* defaults is still a visible swap rather than a no-op — that is how a selected
+* or highlighted row in Glances reads. Invisible is then conceal-by-equality
+* (foreground painted in its own background): the cell keeps its columns, which
+* a dropped cell would not, and dropping it would shift the whole rest of the
+* row left.
+*/
+function resolveCellStyle(cell) {
+	const inverse = cell.isInverse() !== 0;
+	const plainFg = resolveForeground(cell);
+	const plainBg = resolveBackground(cell);
+	const background = inverse ? plainFg : plainBg;
+	let foreground = inverse ? plainBg : plainFg;
+	if (cell.isDim() !== 0) foreground = blend(foreground, background, TERMINAL_DIM_WEIGHT);
+	if (cell.isInvisible() !== 0) foreground = background;
+	return {
+		fg: foreground === "#d7dce2" ? null : foreground,
+		bg: background === "#0b0d10" ? null : background,
+		bold: cell.isBold() !== 0
+	};
+}
+function sameStyle(left, right) {
+	return left.fg === right.fg && left.bg === right.bg && left.bold === right.bold;
+}
+/**
+* Merge adjacent same-style cells into runs, then drop the trailing run of
+* default-styled whitespace so a row costs what it draws — the same trim
+* `translateToString(true)` performs. Whitespace carrying a BACKGROUND is kept:
+* a green bar of spaces out to the right margin is a pixel Glances drew.
+*/
+function buildCellRuns(cells) {
+	const runs = [];
+	let text = "";
+	let style = null;
+	for (const cell of cells) {
+		if (style !== null && sameStyle(style, cell.style)) {
+			text += cell.text;
+			continue;
+		}
+		if (style !== null) runs.push({
+			text,
+			...style
+		});
+		text = cell.text;
+		style = cell.style;
+	}
+	if (style !== null) runs.push({
+		text,
+		...style
+	});
+	while (runs.length > 0) {
+		const last = runs[runs.length - 1];
+		if (last === void 0 || last.bg !== null) break;
+		const trimmed = last.text.replace(/\s+$/u, "");
+		if (trimmed === last.text) break;
+		if (trimmed === "") {
+			runs.pop();
+			continue;
+		}
+		runs[runs.length - 1] = {
+			...last,
+			text: trimmed
+		};
+		break;
+	}
+	return runs;
+}
+/**
+* Monospace families to try, in order — NOT one family and a generic.
+*
+* A terminal screen is mostly box-drawing and block characters, and a font
+* without them renders the frame as noise rather than as missing detail.
+* `DejaVu Sans Mono` covers them and ships in the hub image; macOS has neither
+* DejaVu nor fontconfig, so the Mac agent fell through to a generic whose
+* coverage is not, and its Glances camera came out unreadable while the hub's
+* was pixel-perfect (measured 2026-08-11, same Glances, two nodes).
+*
+* `Menlo` is the fix rather than a guess: it is macOS's default terminal face,
+* present on every install, and derived from DejaVu Sans Mono — the same glyph
+* coverage by ancestry. Monaco and Courier New follow as older fallbacks; the
+* generic stays last so a host with none of them still draws something.
+*/
+var TERMINAL_FONT_STACK = "DejaVu Sans Mono,Menlo,Monaco,Courier New,monospace";
+var TERMINAL_FONT_SIZE = 13;
+var TERMINAL_TEXT_MARGIN_X = 8;
+var TERMINAL_ROW_HEIGHT = 15;
+var TERMINAL_BASELINE_Y = 18;
+/**
+* Distance from a row's baseline up to the top of its cell box. Chosen so
+* consecutive rows tile exactly: row N's box runs from `baseline - this` for
+* `TERMINAL_ROW_HEIGHT`, and row N+1's box starts where it ends. A background
+* bar that stopped short would draw as stripes across a `CSI 42m` panel.
+*/
+var TERMINAL_CELL_ASCENT = 11.5;
+var TERMINAL_CELL_WIDTH = TERMINAL_FONT_SIZE * (1233 / 2048);
+/** Two decimals is under a tenth of a pixel and keeps the SVG small. */
+function coordinate(value) {
+	return String(Number(value.toFixed(2)));
+}
 function escapeXml(value) {
 	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
 }
@@ -33499,11 +33940,47 @@ function escapeXml(value) {
 * looked perfect — which is exactly how the operator reported it. Measured in
 * the hub's own rasterizer 2026-08-11: `AAA<10 spaces>BBB<3>CCC` drew 92 px
 * collapsed against 178 px preserved.
-*/
-async function renderTerminalJpeg(lines) {
-	const renderedLines = lines.slice(0, 40).map((line, index) => `<text xml:space="preserve" x="8" y="${String(18 + index * 15)}">${escapeXml(line.slice(0, 120))}</text>`).join("");
-	const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${String(960)}" height="${String(640)}"><rect width="100%" height="100%" fill="#0b0d10"/><g fill="#d7dce2" font-family="DejaVu Sans Mono,monospace" font-size="13">${renderedLines}</g></svg>`;
-	return sharp(Buffer.from(svg)).jpeg({
+*
+* Every run is anchored at its OWN column (`x = margin + startCol * cellW`),
+* never appended to the one before it, so the background rects and the glyphs
+* are placed off the same grid and cannot drift apart. `textLength` is emitted
+* with it because it is the correct declaration and renderers that honour it
+* get an exact grid — but it is not what makes this work: librsvg, which sharp
+* uses, ignores it outright (measured 2026-08-12, a 120-glyph run pinned to
+* 600 px still drew its natural 937 px). The anchoring is the guarantee.
+*/
+function renderTerminalSvg(rows) {
+	const backgrounds = [];
+	const texts = [];
+	rows.slice(0, 40).forEach((row, index) => {
+		const baseline = TERMINAL_BASELINE_Y + index * TERMINAL_ROW_HEIGHT;
+		const top = baseline - TERMINAL_CELL_ASCENT;
+		let column = 0;
+		for (const run of row) {
+			if (column >= 120) break;
+			const clipped = clipRun(run, 120 - column);
+			const columns = [...clipped].length;
+			if (columns === 0) continue;
+			const x = TERMINAL_TEXT_MARGIN_X + column * TERMINAL_CELL_WIDTH;
+			const width = columns * TERMINAL_CELL_WIDTH;
+			if (run.bg !== null) backgrounds.push(`<rect x="${coordinate(x)}" y="${coordinate(top)}" width="${coordinate(width)}" height="${String(TERMINAL_ROW_HEIGHT)}" fill="${run.bg}"/>`);
+			if (clipped.trim() !== "") {
+				const fill = run.fg === null ? "" : ` fill="${run.fg}"`;
+				const weight = run.bold ? " font-weight=\"bold\"" : "";
+				texts.push(`<text xml:space="preserve" x="${coordinate(x)}" y="${coordinate(baseline)}" textLength="${coordinate(width)}" lengthAdjust="spacingAndGlyphs"${fill}${weight}>${escapeXml(clipped)}</text>`);
+			}
+			column += columns;
+		}
+	});
+	return `<svg xmlns="http://www.w3.org/2000/svg" width="${String(960)}" height="${String(640)}"><rect width="100%" height="100%" fill="${TERMINAL_DEFAULT_BG}"/>${backgrounds.join("")}<g fill="${TERMINAL_DEFAULT_FG}" font-family="${TERMINAL_FONT_STACK}" font-size="${String(TERMINAL_FONT_SIZE)}">${texts.join("")}</g></svg>`;
+}
+/** Cut a run to the columns still left in the row, by code point not unit. */
+function clipRun(run, remaining) {
+	const points = [...run.text];
+	return points.length <= remaining ? run.text : points.slice(0, remaining).join("");
+}
+async function renderTerminalJpeg(rows) {
+	return sharp(Buffer.from(renderTerminalSvg(rows))).jpeg({
 		quality: 82,
 		chromaSubsampling: "4:2:0"
 	}).toBuffer();
@@ -38409,6 +38886,40 @@ function createXtermScreen(cols, rows) {
 			for (let row = 0; row < term.rows; row += 1) lines.push(buffer.getLine(buffer.viewportY + row)?.translateToString(true) ?? "");
 			return lines;
 		},
+		/**
+		* The colour-bearing read. `translateToString` — the only cell read this
+		* screen used to offer — keeps characters and discards every attribute,
+		* which is why the terminal camera rendered a fully-coloured Glances in
+		* grey. Walking cells is the only way to get the attributes back.
+		*
+		* A zero-width cell is the tail half of a wide glyph (CJK, some emoji);
+		* its characters already came back with the leading cell, so skipping it
+		* keeps the text right. `getNullCell()` is reused across the whole screen
+		* because `getCell` allocates otherwise — 4800 objects per frame.
+		*/
+		styledLines: () => {
+			const buffer = term.buffer.active;
+			const scratch = buffer.getNullCell();
+			const styled = [];
+			for (let row = 0; row < term.rows; row += 1) {
+				const line = buffer.getLine(buffer.viewportY + row);
+				if (!line) {
+					styled.push([]);
+					continue;
+				}
+				const cells = [];
+				for (let column = 0; column < line.length; column += 1) {
+					const cell = line.getCell(column, scratch);
+					if (!cell || cell.getWidth() === 0) continue;
+					cells.push({
+						text: cell.getChars() || " ",
+						style: resolveCellStyle(cell)
+					});
+				}
+				styled.push(buildCellRuns(cells));
+			}
+			return styled;
+		},
 		dispose: () => {
 			term.dispose();
 		}
@@ -38419,6 +38930,9 @@ function createXtermScreen(cols, rows) {
 var MJPEG_BOUNDARY = "camstack-terminal-frame";
 var SESSION_IDLE_MS = 3e4;
 var SNAPSHOT_STARTUP_WAIT_MS = 1500;
+var SNAPSHOT_SETTLE_QUIET_MS = 300;
+var SNAPSHOT_SETTLE_BUDGET_MS = 3e3;
+var SNAPSHOT_SETTLE_MAX_PULLS = 20;
 var CLOSE_RETRY_BASE_MS = 50;
 var CLOSE_RETRY_MAX_MS = 1e3;
 var CLOSE_ATTEMPTS_PER_PASS = 3;
@@ -38543,20 +39057,36 @@ var TerminalCameraRelay = class {
 			if (state.openPromise === opening) state.openPromise = null;
 		}
 	}
+	/** Replay one output batch into the relay screen; true = the session exited. */
+	applyBatch(state, batch) {
+		if (batch.reset) {
+			state.screen.dispose();
+			state.screen = createXtermScreen(120, 40);
+			if (batch.snapshot) state.screen.write(batch.snapshot);
+		}
+		let exited = false;
+		for (const event of batch.events) if (event.kind === "data") state.screen.write(event.data);
+		else {
+			state.sessionId = null;
+			exited = true;
+		}
+		state.cursor = exited ? 0 : batch.cursor;
+		return exited;
+	}
 	async nextFrame(state, forceRender = false, waitForInitialOutput = false) {
 		if (state.framePromise) {
 			await state.framePromise;
 			return forceRender ? this.nextFrame(state, true, waitForInitialOutput) : state.jpeg ?? this.nextFrame(state, false, waitForInitialOutput);
 		}
 		const render = async () => {
-			const openingSession = state.sessionId === null;
+			const initialPull = state.sessionId === null && waitForInitialOutput;
 			const sessionId = await this.ensureSession(state);
 			let batch;
 			try {
 				batch = await this.api.pullOutput(state.nodeId, {
 					sessionId,
 					afterSeq: state.cursor,
-					...openingSession && waitForInitialOutput ? {
+					...initialPull ? {
 						waitMs: SNAPSHOT_STARTUP_WAIT_MS,
 						waitForOutput: true
 					} : {}
@@ -38578,21 +39108,29 @@ var TerminalCameraRelay = class {
 				state.cursor = 0;
 				throw error;
 			}
-			if (batch.reset) {
-				state.screen.dispose();
-				state.screen = createXtermScreen(120, 40);
-				if (batch.snapshot) state.screen.write(batch.snapshot);
-			}
-			let exited = false;
-			for (const event of batch.events) if (event.kind === "data") state.screen.write(event.data);
-			else {
-				state.sessionId = null;
-				exited = true;
+			let exited = this.applyBatch(state, batch);
+			if (initialPull && !exited) {
+				const deadline = Date.now() + SNAPSHOT_SETTLE_BUDGET_MS;
+				for (let pulls = 0; pulls < SNAPSHOT_SETTLE_MAX_PULLS && Date.now() < deadline; pulls += 1) {
+					let settle;
+					try {
+						settle = await this.api.pullOutput(state.nodeId, {
+							sessionId,
+							afterSeq: state.cursor,
+							waitMs: SNAPSHOT_SETTLE_QUIET_MS,
+							waitForOutput: true
+						});
+					} catch {
+						break;
+					}
+					const active = settle.reset || settle.events.some((event) => event.kind === "data");
+					exited = this.applyBatch(state, settle);
+					if (exited || !active) break;
+				}
 			}
-			state.cursor = exited ? 0 : batch.cursor;
 			await state.screen.flush();
 			if (forceRender || state.jpeg === null || state.renderedCursor !== state.cursor) {
-				state.jpeg = await renderTerminalJpeg(state.screen.lines());
+				state.jpeg = await renderTerminalJpeg(state.screen.styledLines());
 				state.renderedCursor = state.cursor;
 			}
 			return state.jpeg;
@@ -39041,7 +39579,8 @@ function buildProfiles(options) {
 				"-m",
 				"glances",
 				...options.glancesArgs ?? []
-			]
+			],
+			...options.glancesEnv && Object.keys(options.glancesEnv).length > 0 ? { env: options.glancesEnv } : {}
 		});
 	}
 	if (options.allowShell) profiles.push({
@@ -39126,6 +39665,7 @@ var TerminalSessionManager = class {
 			glancesPath: opts.glancesPath,
 			glancesArgs: opts.glancesArgs,
 			glancesPythonPath: opts.glancesPythonPath,
+			glancesEnv: opts.glancesEnv,
 			allowShell: opts.allowShell,
 			shellPath: opts.shellPath,
 			customProfiles: opts.customProfiles,
@@ -39423,6 +39963,18 @@ var TerminalSessionManager = class {
 };
 //#endregion
 //#region src/addon.ts
+/**
+* Terminal addon — hosts interactive pty sessions running an allowlisted
+* profile (`monitor` → `btm`), streamed to the Admin UI over the data plane.
+*
+* Phase 1 of docs/design/2026-07-26-terminal-session-design.md: a real TTY good
+* enough to run a full-screen program. Phase 2 (streaming a session as a camera)
+* is a separate device-provider concern and does not change this addon's cap.
+*
+* Its own package (not a builtin) because it carries a native dependency
+* (`node-pty`) and should update via `camstack deploy` independently of the
+* framework, exactly like the node-av decoder addon.
+*/
 var DEFAULTS = {
 	btmPath: "",
 	btmEnabled: true,
@@ -39455,12 +40007,21 @@ var TerminalAddon = class extends BaseAddon {
 	instanceMutationQueue = new TerminalInstanceMutationQueue();
 	terminalReconcileCoordinator = new TerminalInstanceReconcileCoordinator(this.instanceMutationQueue);
 	glancesPythonPath = "";
+	glancesEnv;
 	constructor() {
 		super({ ...DEFAULTS });
 	}
 	async onInitialize() {
 		await warmNodePty();
 		this.glancesPythonPath = await this.ctx.deps.ensurePython() ?? "";
+		const shimDir = cursesShimDir();
+		this.glancesEnv = resolveGlancesCursesShimEnv({
+			platform: process.platform,
+			shimDir,
+			shimDirExists: cursesShimDirExists(shimDir),
+			existingPythonPath: process.env["PYTHONPATH"]
+		});
+		this.probeGlancesCursesColours();
 		const manager = new TerminalSessionManager({
 			spawn: createNodePtySpawner(),
 			screenFactory: createXtermScreen,
@@ -39476,6 +40037,7 @@ var TerminalAddon = class extends BaseAddon {
 			glancesPath: this.config.glancesPath,
 			glancesArgs: this.config.glancesArgs,
 			glancesPythonPath: this.glancesPythonPath,
+			glancesEnv: this.glancesEnv,
 			allowShell: this.config.allowShell,
 			shellPath: this.config.shellPath,
 			maxSessions: this.config.maxSessions,
@@ -39521,6 +40083,39 @@ var TerminalAddon = class extends BaseAddon {
 			provider: manager
 		}];
 	}
+	/**
+	* Fire-and-forget canary: the managed python must see a colour-capable
+	* curses, or glances paints its B&W theme (SGR conceal/reverse) and the
+	* terminal camera frames lose their text. The shim filename is ABI-locked
+	* (cpython-312), so a managed-python bump silently disables it — this probe
+	* is what makes that failure loud instead of a garbled camera.
+	*/
+	probeGlancesCursesColours() {
+		if (!this.glancesPythonPath) return;
+		const probeEnv = {
+			...process.env,
+			...this.glancesEnv,
+			TERM: "xterm-256color"
+		};
+		execFile(this.glancesPythonPath, ["-c", "import curses\ncurses.setupterm('xterm-256color')\nprint(curses.tigetnum('colors'))"], {
+			env: probeEnv,
+			timeout: 1e4
+		}, (error, stdout) => {
+			const colours = error ? NaN : Number.parseInt(stdout.trim(), 10);
+			if (!Number.isFinite(colours) || colours <= 0) {
+				this.ctx.logger.warn("glances curses reports no colours — terminal camera frames will render the B&W theme", { meta: {
+					colours: Number.isFinite(colours) ? colours : null,
+					shimApplied: this.glancesEnv !== void 0,
+					error: error ? error instanceof Error ? error.message : String(error) : void 0
+				} });
+				return;
+			}
+			this.ctx.logger.debug("glances curses colours available", { meta: {
+				colours,
+				shimApplied: this.glancesEnv !== void 0
+			} });
+		});
+	}
 	async onConfigChanged() {
 		this.replaceTerminalCameraTombstones(this.config.terminalCameraTombstones);
 		this.manager?.reconfigureProfiles({
@@ -39534,6 +40129,7 @@ var TerminalAddon = class extends BaseAddon {
 			glancesPath: this.config.glancesPath,
 			glancesArgs: this.config.glancesArgs,
 			glancesPythonPath: this.glancesPythonPath,
+			glancesEnv: this.glancesEnv,
 			allowShell: this.config.allowShell,
 			shellPath: this.config.shellPath,
 			maxSessions: this.config.maxSessions,
@@ -39637,37 +40233,22 @@ var TerminalAddon = class extends BaseAddon {
 		}
 	}
 	/**
-	* A Terminal camera is a rendered screen. Object detection on it finds
-	* nothing, forever, at full cost.
-	*
-	* Measured on the hub 2026-08-11, for ONE terminal camera: 19 frames per 10 s
-	* through the detection pipeline at ~61 ms of inference each, plus 115
-	* capture-scheduler requests a minute — against `detections=0`. Multiply by
-	* one terminal per node and it is a standing tax on a hub that was already
-	* shedding 86 % of its capture queue.
+	* A Terminal camera is a rendered screen. Every analyzer on it finds nothing,
+	* forever, at full cost — see `silence-analysis.ts` for the measurements, the
+	* reason `motion-detection` is in the list, and why a failure THROWS instead
+	* of warning.
 	*
-	* Written through `setCameraSwitch`, which is the authority that already owns
-	* this function — [D62] forbids a second store that disagrees with it. And
-	* written ONLY on creation: an operator who deliberately turns detection back
-	* on for a terminal must win, and a reconcile that re-asserted every pass
-	* would silently overrule them once a minute.
-	*/
-	async silenceAnalysisFor(deviceId) {
-		for (const switchId of ["object-detection", "audio-analysis"]) try {
-			await this.ctx.api.pipelineOrchestrator.setCameraSwitch.mutate({
-				deviceId,
-				switchId,
-				enabled: false
-			});
-		} catch (err) {
-			this.ctx.logger.warn("could not switch off analysis for a Terminal camera", {
-				tags: { deviceId },
-				meta: {
-					switchId,
-					error: err instanceof Error ? err.message : String(err)
-				}
-			});
-		}
+	* Written to the AUTHORITIES (`deviceManager.setWrapperActive`), not through
+	* the deprecated switch cap the previous version used (D113). Written ONLY on
+	* creation: an operator who deliberately turns detection back on for a
+	* terminal must win, and a reconcile that re-asserted every pass would
+	* silently overrule them once a minute.
+	*/
+	silenceAnalysisFor(deviceId) {
+		return silenceAnalysisFor({
+			api: this.ctx.api,
+			logger: this.ctx.logger
+		}, deviceId);
 	}
 	terminalInstanceControl() {
 		return {
@@ -39980,4 +40561,4 @@ var TerminalAddon = class extends BaseAddon {
 	}
 };
 //#endregion
-export { TerminalAddon, createXtermScreen as a, createTerminalDataPlaneHandler as i, buildProfiles as n, createNodePtySpawner as o, findProfile as r, warmNodePty as s, TerminalSessionManager as t };
+export { TerminalAddon, createXtermScreen as a, buildCellRuns as c, terminalRgbColor as d, createNodePtySpawner as f, createTerminalDataPlaneHandler as i, resolveCellStyle as l, buildProfiles as n, TERMINAL_DEFAULT_BG as o, warmNodePty as p, findProfile as r, TERMINAL_DEFAULT_FG as s, TerminalSessionManager as t, terminalPaletteColor as u };