@camstack/addon-terminal 0.1.13 → 0.1.15

package/dist/addon.js

@@ -22,9 +22,12 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
+let node_child_process = require("node:child_process");
 let node_fs = require("node:fs");
-let node_module = require("node:module");
 let node_path = require("node:path");
+node_path = __toESM(node_path);
+let node_url = require("node:url");
+let node_module = require("node:module");
 let sharp = require("sharp");
 sharp = __toESM(sharp);
 let node_http = require("node:http");
@@ -33377,6 +33380,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 node_path.default.join(node_path.default.dirname((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href)), "..", "assets", "curses-shim", "py312");
+}
+function cursesShimDirExists(shimDir) {
+	return (0, node_fs.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
@@ -33507,6 +33550,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;");
 }
@@ -33521,11 +33756,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 (0, sharp.default)(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 (0, sharp.default)(Buffer.from(renderTerminalSvg(rows))).jpeg({
 		quality: 82,
 		chromaSubsampling: "4:2:0"
 	}).toBuffer();
@@ -38431,6 +38702,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();
 		}
@@ -38441,6 +38746,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;
@@ -38565,20 +38873,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
 					} : {}
@@ -38600,21 +38924,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;
@@ -39063,7 +39395,8 @@ function buildProfiles(options) {
 				"-m",
 				"glances",
 				...options.glancesArgs ?? []
-			]
+			],
+			...options.glancesEnv && Object.keys(options.glancesEnv).length > 0 ? { env: options.glancesEnv } : {}
 		});
 	}
 	if (options.allowShell) profiles.push({
@@ -39148,6 +39481,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,
@@ -39445,6 +39779,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,
@@ -39477,12 +39823,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,
@@ -39498,6 +39853,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,
@@ -39543,6 +39899,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"
+		};
+		(0, node_child_process.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({
@@ -39556,6 +39945,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,
@@ -40002,11 +40392,17 @@ var TerminalAddon = class extends BaseAddon {
 	}
 };
 //#endregion
+exports.TERMINAL_DEFAULT_BG = TERMINAL_DEFAULT_BG;
+exports.TERMINAL_DEFAULT_FG = TERMINAL_DEFAULT_FG;
 exports.TerminalAddon = TerminalAddon;
 exports.TerminalSessionManager = TerminalSessionManager;
+exports.buildCellRuns = buildCellRuns;
 exports.buildProfiles = buildProfiles;
 exports.createNodePtySpawner = createNodePtySpawner;
 exports.createTerminalDataPlaneHandler = createTerminalDataPlaneHandler;
 exports.createXtermScreen = createXtermScreen;
 exports.findProfile = findProfile;
+exports.resolveCellStyle = resolveCellStyle;
+exports.terminalPaletteColor = terminalPaletteColor;
+exports.terminalRgbColor = terminalRgbColor;
 exports.warmNodePty = warmNodePty;

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
@@ -33355,6 +33357,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
@@ -33485,6 +33527,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 +33733,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 +38679,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 +38723,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 +38850,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 +38901,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 +39372,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 +39458,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 +39756,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 +39800,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 +39830,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 +39876,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 +39922,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,
@@ -39980,4 +40369,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 };

package/dist/index.js

@@ -3,12 +3,18 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_addon = require("./addon.js");
+exports.TERMINAL_DEFAULT_BG = require_addon.TERMINAL_DEFAULT_BG;
+exports.TERMINAL_DEFAULT_FG = require_addon.TERMINAL_DEFAULT_FG;
 exports.TerminalAddon = require_addon.TerminalAddon;
 exports.TerminalSessionManager = require_addon.TerminalSessionManager;
+exports.buildCellRuns = require_addon.buildCellRuns;
 exports.buildProfiles = require_addon.buildProfiles;
 exports.createNodePtySpawner = require_addon.createNodePtySpawner;
 exports.createTerminalDataPlaneHandler = require_addon.createTerminalDataPlaneHandler;
 exports.createXtermScreen = require_addon.createXtermScreen;
 exports.default = require_addon.TerminalAddon;
 exports.findProfile = require_addon.findProfile;
+exports.resolveCellStyle = require_addon.resolveCellStyle;
+exports.terminalPaletteColor = require_addon.terminalPaletteColor;
+exports.terminalRgbColor = require_addon.terminalRgbColor;
 exports.warmNodePty = require_addon.warmNodePty;

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { TerminalAddon, a as createXtermScreen, i as createTerminalDataPlaneHandler, n as buildProfiles, o as createNodePtySpawner, r as findProfile, s as warmNodePty, t as TerminalSessionManager } from "./addon.mjs";
-export { TerminalAddon, TerminalAddon as default, TerminalSessionManager, buildProfiles, createNodePtySpawner, createTerminalDataPlaneHandler, createXtermScreen, findProfile, warmNodePty };
+import { TerminalAddon, a as createXtermScreen, c as buildCellRuns, d as terminalRgbColor, f as createNodePtySpawner, i as createTerminalDataPlaneHandler, l as resolveCellStyle, n as buildProfiles, o as TERMINAL_DEFAULT_BG, p as warmNodePty, r as findProfile, s as TERMINAL_DEFAULT_FG, t as TerminalSessionManager, u as terminalPaletteColor } from "./addon.mjs";
+export { TERMINAL_DEFAULT_BG, TERMINAL_DEFAULT_FG, TerminalAddon, TerminalAddon as default, TerminalSessionManager, buildCellRuns, buildProfiles, createNodePtySpawner, createTerminalDataPlaneHandler, createXtermScreen, findProfile, resolveCellStyle, terminalPaletteColor, terminalRgbColor, warmNodePty };

package/package.json

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