@nocville/npc 0.2.1 → 0.2.3

package/dist/npcs/receptionist/weather.js

@@ -1,8 +1,11 @@
 /**
- * Keyless weather + geolocation via open-meteo, with ipapi.co IP fallback.
- * All network helpers return null on failure so the receptionist can degrade
- * to a time-only mode without erroring.
+ * Keyless weather + geolocation via open-meteo, with an optional ipapi.co IP
+ * fallback. Every call is time- and size-bounded, validates the (untrusted)
+ * response, and returns null on failure so the receptionist can degrade to a
+ * time-only mode without erroring.
  */
+import { asRecord, fetchJson, finiteNumber } from '../../core/http.js';
+import { sanitizeText } from '../../core/text.js';
 // WMO weather-interpretation codes → human text + a glyph keyword the
 // welcome-sign renderer understands (matched by /sun|clear|partly|rain|snow|storm|fog/).
 const WMO = {
@@ -39,65 +42,56 @@ const WMO = {
 export function describeWmo(code) {
     return WMO[code] ?? { text: 'Unknown', icon: 'cloud' };
 }
-async function fetchJson(url, timeoutMs) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-        const res = await fetch(url, {
-            signal: controller.signal,
-            headers: { 'User-Agent': 'nocville-npc' },
-        });
-        if (!res.ok)
-            return null;
-        return (await res.json());
-    }
-    catch {
-        return null;
-    }
-    finally {
-        clearTimeout(timer);
-    }
+/** A finite, in-range latitude/longitude pair. */
+export function validCoords(lat, lon) {
+    const la = finiteNumber(lat);
+    const lo = finiteNumber(lon);
+    return la !== null && lo !== null && Math.abs(la) <= 90 && Math.abs(lo) <= 180;
 }
-/** Resolve a place name to coordinates via the open-meteo geocoding API. */
-export async function geocodeLocation(name, timeoutMs = 5000) {
-    const url = `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(name)}&count=1`;
-    const res = await fetchJson(url, timeoutMs);
-    const first = res?.['results']?.[0];
-    if (!first || typeof first['latitude'] !== 'number')
+function coordsFrom(rec, labelKey) {
+    if (!validCoords(rec['latitude'], rec['longitude']))
         return null;
+    const label = rec[labelKey];
     return {
-        lat: first['latitude'],
-        lon: first['longitude'],
-        label: first['name'] ?? name,
+        lat: rec['latitude'],
+        lon: rec['longitude'],
+        label: typeof label === 'string' ? sanitizeText(label, 60) : undefined,
     };
 }
-/** Best-effort IP geolocation via ipapi.co (keyless). */
+/** Resolve a place name to coordinates via the open-meteo geocoding API. */
+export async function geocodeLocation(name, timeoutMs = 5000) {
+    const url = 'https://geocoding-api.open-meteo.com/v1/search' +
+        `?name=${encodeURIComponent(name.slice(0, 100))}&count=1`;
+    const results = asRecord(await fetchJson(url, { timeoutMs }))?.['results'];
+    const first = Array.isArray(results) ? asRecord(results[0]) : null;
+    return first ? coordsFrom(first, 'name') : null;
+}
+/**
+ * Best-effort IP geolocation via ipapi.co (keyless). This sends the machine's
+ * public IP to a third party, so the receptionist only calls it when no place
+ * was configured and the user hasn't opted out. Only the coordinates are used;
+ * nothing from the response is pushed to Nocville.
+ */
 export async function autoGeo(timeoutMs = 5000) {
-    const res = await fetchJson('https://ipapi.co/json/', timeoutMs);
-    if (!res || typeof res['latitude'] !== 'number')
-        return null;
-    return {
-        lat: res['latitude'],
-        lon: res['longitude'],
-        label: res['city'],
-    };
+    const res = asRecord(await fetchJson('https://ipapi.co/json/', { timeoutMs }));
+    return res ? coordsFrom(res, 'city') : null;
 }
 /** Fetch current temperature, weather code, and wind for coordinates. */
 export async function fetchWeather(coords, timeoutMs = 5000) {
     const url = `https://api.open-meteo.com/v1/forecast?latitude=${coords.lat}` +
         `&longitude=${coords.lon}&current=temperature_2m,weather_code,wind_speed_10m`;
-    const res = await fetchJson(url, timeoutMs);
-    const cur = res?.['current'];
-    if (!cur || typeof cur['temperature_2m'] !== 'number')
+    const cur = asRecord(asRecord(await fetchJson(url, { timeoutMs }))?.['current']);
+    const temp = finiteNumber(cur?.['temperature_2m']);
+    if (!cur || temp === null || Math.abs(temp) > 100)
         return null;
-    const code = Number(cur['weather_code'] ?? 0);
+    const code = finiteNumber(cur['weather_code']) ?? -1;
     const { text, icon } = describeWmo(code);
     return {
-        tempC: Math.round(cur['temperature_2m']),
+        tempC: Math.round(temp),
         code,
         text,
         icon,
-        windKph: Math.round(Number(cur['wind_speed_10m'] ?? 0)),
+        windKph: Math.round(Math.max(0, finiteNumber(cur['wind_speed_10m']) ?? 0)),
     };
 }
 /** Convert Celsius to Fahrenheit, rounded. */

package/dist/npcs/system-monitor/collectors.d.ts

@@ -34,11 +34,23 @@ export declare function createCpuSampler(readCpus?: () => Array<{
     times: CpuTimes;
 }>, readLoad?: () => number): CpuSampler;
 /**
- * Collect memory usage from OS.
+ * Parse `vm_stat` output into reclaimable ("available") bytes: free +
+ * inactive + speculative pages, the same estimate psutil uses on macOS.
+ * Returns null when the output is unrecognised.
  */
-export declare function collectMemory(): MemMetrics;
+export declare function parseVmStat(stdout: string): number | null;
 /**
- * Collect disk usage via fs.statfs (Node 18.15+).
+ * Bytes of memory available to new work. On macOS `os.freemem()` counts only
+ * never-used pages (the file cache is "used"), which reads ~95% full on any
+ * healthy Mac, so the reclaimable estimate comes from `vm_stat` instead. Linux
+ * (`MemAvailable`) and Windows report a meaningful value through Node.
+ */
+export declare function readAvailableMemory(): Promise<number>;
+/** Memory usage from the total and the available byte count. */
+export declare function collectMemory(availableBytes?: number, totalBytes?: number): MemMetrics;
+/**
+ * Disk usage via fs.statfs, computed like `df`: used / (used + available to
+ * unprivileged users), so blocks reserved for root don't hide a full disk.
  */
 export declare function collectDisk(path: string): Promise<DiskMetrics>;
 export {};

package/dist/npcs/system-monitor/collectors.js

@@ -1,5 +1,8 @@
 import os from 'node:os';
 import { promises as fsp } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
 function aggregate(cpus) {
     let idle = 0;
     let total = 0;
@@ -10,6 +13,12 @@ function aggregate(cpus) {
     }
     return { idle, total };
 }
+function gb(bytes) {
+    return Math.round((bytes / 1024 ** 3) * 100) / 100;
+}
+function percentOf(part, whole) {
+    return whole > 0 ? Math.min(100, Math.max(0, Math.round((part / whole) * 100))) : 0;
+}
 /**
  * Stateful CPU sampler that computes usage from the delta between consecutive
  * `os.cpus()` snapshots — no blocking sleep. The first sample reports usage
@@ -27,34 +36,72 @@ export function createCpuSampler(readCpus = () => os.cpus(), readLoad = () => os
             const idleDiff = cur.idle - base.idle;
             const totalDiff = cur.total - base.total;
             prev = cur;
-            const percent = totalDiff > 0 ? Math.round((1 - idleDiff / totalDiff) * 100) : 0;
+            const percent = totalDiff > 0 ? percentOf(totalDiff - idleDiff, totalDiff) : 0;
             return { percent, loadAvg1m };
         },
     };
 }
 /**
- * Collect memory usage from OS.
+ * Parse `vm_stat` output into reclaimable ("available") bytes: free +
+ * inactive + speculative pages, the same estimate psutil uses on macOS.
+ * Returns null when the output is unrecognised.
+ */
+export function parseVmStat(stdout) {
+    const pageSize = Number(stdout.match(/page size of (\d+) bytes/)?.[1]);
+    if (!Number.isFinite(pageSize) || pageSize <= 0)
+        return null;
+    const pages = (label) => {
+        const m = stdout.match(new RegExp(`^Pages ${label}:\\s+(\\d+)`, 'm'));
+        return m ? Number(m[1]) : null;
+    };
+    const free = pages('free');
+    const inactive = pages('inactive');
+    if (free === null || inactive === null)
+        return null;
+    return (free + inactive + (pages('speculative') ?? 0)) * pageSize;
+}
+/**
+ * Bytes of memory available to new work. On macOS `os.freemem()` counts only
+ * never-used pages (the file cache is "used"), which reads ~95% full on any
+ * healthy Mac, so the reclaimable estimate comes from `vm_stat` instead. Linux
+ * (`MemAvailable`) and Windows report a meaningful value through Node.
  */
-export function collectMemory() {
-    const totalBytes = os.totalmem();
-    const freeBytes = os.freemem();
-    const usedBytes = totalBytes - freeBytes;
-    const totalGb = Math.round((totalBytes / 1024 ** 3) * 100) / 100;
-    const usedGb = Math.round((usedBytes / 1024 ** 3) * 100) / 100;
-    const percent = Math.round((usedBytes / totalBytes) * 100);
-    return { percent, usedGb, totalGb };
+export async function readAvailableMemory() {
+    if (process.platform === 'darwin') {
+        try {
+            const { stdout } = await execFileAsync('vm_stat', [], { timeout: 2000 });
+            const available = parseVmStat(stdout);
+            if (available !== null)
+                return Math.min(available, os.totalmem());
+        }
+        catch {
+            // Fall through to Node's figure.
+        }
+    }
+    return os.freemem();
+}
+/** Memory usage from the total and the available byte count. */
+export function collectMemory(availableBytes = os.freemem(), totalBytes = os.totalmem()) {
+    const usedBytes = Math.max(0, totalBytes - availableBytes);
+    return {
+        percent: percentOf(usedBytes, totalBytes),
+        usedGb: gb(usedBytes),
+        totalGb: gb(totalBytes),
+    };
 }
 /**
- * Collect disk usage via fs.statfs (Node 18.15+).
+ * Disk usage via fs.statfs, computed like `df`: used / (used + available to
+ * unprivileged users), so blocks reserved for root don't hide a full disk.
  */
 export async function collectDisk(path) {
     const stats = await fsp.statfs(path);
     const totalBytes = stats.blocks * stats.bsize;
-    const freeBytes = stats.bavail * stats.bsize;
-    const usedBytes = totalBytes - freeBytes;
-    const totalGb = Math.round((totalBytes / 1024 ** 3) * 100) / 100;
-    const usedGb = Math.round((usedBytes / 1024 ** 3) * 100) / 100;
-    const percent = totalBytes > 0 ? Math.round((usedBytes / totalBytes) * 100) : 0;
-    return { percent, usedGb, totalGb };
+    const usedBytes = (stats.blocks - stats.bfree) * stats.bsize;
+    const availBytes = stats.bavail * stats.bsize;
+    return {
+        percent: percentOf(usedBytes, usedBytes + availBytes),
+        usedGb: gb(usedBytes),
+        totalGb: gb(totalBytes),
+    };
 }
 //# sourceMappingURL=collectors.js.map

package/dist/npcs/system-monitor/defaults.d.ts

@@ -3,5 +3,5 @@ export declare const DEFAULTS: {
     pollInterval: number;
     diskPath: string;
 };
-export declare const DEFAULT_THRESHOLDS: Record<string, ThresholdConfig>;
+export declare const DEFAULT_THRESHOLDS: Record<'cpu' | 'mem' | 'disk', ThresholdConfig>;
 //# sourceMappingURL=defaults.d.ts.map

package/dist/npcs/system-monitor/index.d.ts

@@ -15,13 +15,14 @@ export declare class SystemMonitorNPC extends PollingNPC {
     private cpuSampler;
     private cpuHistory;
     private memHistory;
+    private diskErrorLogged;
     constructor(config: SystemMonitorConfig);
     get name(): string;
     protected get defaultDisplayName(): string;
     get archetype(): Archetype;
-    get heartbeatSeconds(): number;
     get behavior(): BehaviorHints;
     get companion(): CompanionDecl;
     protected collect(): Promise<CollectedMetrics>;
+    private readDisk;
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/npcs/system-monitor/index.js

@@ -1,7 +1,8 @@
 import { PollingNPC } from '../../core/polling-npc.js';
-import { evaluateThreshold, worstStatus } from '../../core/thresholds.js';
+import { evaluateThreshold, worstStatus, moodForStatus, thresholdProblem, } from '../../core/thresholds.js';
 import { statusColor, pushHistory } from '../../core/screen.js';
-import { createCpuSampler, collectMemory, collectDisk } from './collectors.js';
+import { NpcConfigError } from '../../core/errors.js';
+import { createCpuSampler, collectMemory, collectDisk, readAvailableMemory } from './collectors.js';
 import { DEFAULTS, DEFAULT_THRESHOLDS } from './defaults.js';
 export class SystemMonitorNPC extends PollingNPC {
     diskPath;
@@ -11,15 +12,21 @@ export class SystemMonitorNPC extends PollingNPC {
     cpuSampler = createCpuSampler();
     cpuHistory = [];
     memHistory = [];
+    diskErrorLogged = false;
     constructor(config) {
         super({
             ...config,
             pollInterval: config.pollInterval ?? DEFAULTS.pollInterval,
         });
         this.diskPath = config.diskPath ?? DEFAULTS.diskPath;
-        this.cpuThreshold = config.cpuThreshold ?? DEFAULT_THRESHOLDS['cpu'];
-        this.memThreshold = config.memThreshold ?? DEFAULT_THRESHOLDS['mem'];
-        this.diskThreshold = config.diskThreshold ?? DEFAULT_THRESHOLDS['disk'];
+        this.cpuThreshold = config.cpuThreshold ?? DEFAULT_THRESHOLDS.cpu;
+        this.memThreshold = config.memThreshold ?? DEFAULT_THRESHOLDS.mem;
+        this.diskThreshold = config.diskThreshold ?? DEFAULT_THRESHOLDS.disk;
+        const problem = thresholdProblem('CPU', this.cpuThreshold) ??
+            thresholdProblem('Memory', this.memThreshold) ??
+            thresholdProblem('Disk', this.diskThreshold);
+        if (problem)
+            throw new NpcConfigError(problem);
     }
     get name() {
         return 'system-monitor';
@@ -30,9 +37,6 @@ export class SystemMonitorNPC extends PollingNPC {
     get archetype() {
         return 'service';
     }
-    get heartbeatSeconds() {
-        return 30;
-    }
     get behavior() {
         return { idle: 'wander' };
     }
@@ -46,19 +50,20 @@ export class SystemMonitorNPC extends PollingNPC {
     }
     async collect() {
         const cpu = this.cpuSampler.sample();
-        const mem = collectMemory();
-        const disk = await collectDisk(this.diskPath);
+        const mem = collectMemory(await readAvailableMemory());
+        const disk = await this.readDisk();
         const cpuStatus = evaluateThreshold(cpu.percent, this.cpuThreshold);
         const memStatus = evaluateThreshold(mem.percent, this.memThreshold);
-        const diskStatus = evaluateThreshold(disk.percent, this.diskThreshold);
+        // An unreadable disk (unmounted volume, bad --disk-path) is a warning, not a crash.
+        const diskStatus = disk
+            ? evaluateThreshold(disk.percent, this.diskThreshold)
+            : 'warning';
         const status = worstStatus([cpuStatus, memStatus, diskStatus]);
-        const mood = status === 'critical'
-            ? 'stressed'
-            : status === 'warning'
-                ? 'concerned'
-                : 'happy';
         pushHistory(this.cpuHistory, cpu.percent);
         pushHistory(this.memHistory, mem.percent);
+        const diskText = disk ? `${disk.percent}%` : 'n/a';
+        // Windows has no load average (os.loadavg() is always zeros there).
+        const loadText = process.platform === 'win32' ? 'n/a' : cpu.loadAvg1m.toFixed(2);
         const screenData = {
             layout: 'multi-metric',
             values: [
@@ -74,28 +79,47 @@ export class SystemMonitorNPC extends PollingNPC {
                     color: statusColor(memStatus),
                     sparkline: [...this.memHistory],
                 },
-                { label: 'DISK', value: `${disk.percent}%`, color: statusColor(diskStatus) },
-                { label: 'LOAD', value: cpu.loadAvg1m.toFixed(2), color: 'gray' },
+                { label: 'DISK', value: diskText, color: statusColor(diskStatus) },
+                { label: 'LOAD', value: loadText, color: 'gray' },
             ],
         };
+        const metrics = {
+            cpu_percent: cpu.percent,
+            mem_percent: mem.percent,
+            mem_used_gb: mem.usedGb,
+            mem_total_gb: mem.totalGb,
+            load_avg_1m: cpu.loadAvg1m,
+        };
+        if (disk) {
+            metrics['disk_percent'] = disk.percent;
+            metrics['disk_used_gb'] = disk.usedGb;
+            metrics['disk_total_gb'] = disk.totalGb;
+        }
         return {
             status,
-            mood,
-            message: `CPU: ${cpu.percent}% | Mem: ${mem.percent}% | Disk: ${disk.percent}%`,
+            mood: moodForStatus(status),
+            message: `CPU: ${cpu.percent}% | Mem: ${mem.percent}% | Disk: ${disk ? diskText : 'unavailable'}`,
             screenData,
             // When strained, go find a desk and get to work; otherwise wander.
             behavior: status !== 'healthy' ? { busy: 'seek-desk' } : undefined,
-            metrics: {
-                cpu_percent: cpu.percent,
-                mem_percent: mem.percent,
-                mem_used_gb: mem.usedGb,
-                mem_total_gb: mem.totalGb,
-                disk_percent: disk.percent,
-                disk_used_gb: disk.usedGb,
-                disk_total_gb: disk.totalGb,
-                load_avg_1m: cpu.loadAvg1m,
-            },
+            metrics,
         };
     }
+    async readDisk() {
+        try {
+            const disk = await collectDisk(this.diskPath);
+            this.diskErrorLogged = false;
+            return disk;
+        }
+        catch (err) {
+            if (!this.diskErrorLogged) {
+                this.diskErrorLogged = true;
+                this.logger.warn(`Cannot read disk usage for ${this.diskPath}`, {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            return null;
+        }
+    }
 }
 //# sourceMappingURL=index.js.map

package/dist/npcs/web-page-watcher/basic-mode.d.ts

@@ -5,12 +5,12 @@ export interface BasicCheck {
     ok: boolean;
     timedOut: boolean;
 }
-/** Extract the <title> text from an HTML string (empty if none). */
+/** Extract the <title> text from (untrusted) HTML: entities decoded, sanitized, ≤80 chars. */
 export declare function extractTitle(html: string): string;
 /** Map an HTTP status to NPC status: 2xx/3xx ok, 4xx/timeout warn, 5xx/refused crit. */
 export declare function statusFromHttp(code: number, timedOut?: boolean): Status;
 /** Fetch a page and extract HTTP status + <title> (basic, no browser). */
 export declare function basicCheck(url: string, timeoutMs?: number): Promise<BasicCheck>;
-/** Best-effort hostname for a URL, falling back to the raw string. */
+/** Hostname of a URL for labels and service ids (never credentials or path). */
 export declare function hostnameOf(url: string): string;
 //# sourceMappingURL=basic-mode.d.ts.map

package/dist/npcs/web-page-watcher/basic-mode.js

@@ -1,7 +1,28 @@
-/** Extract the <title> text from an HTML string (empty if none). */
+import { NPC_USER_AGENT, readTextCapped } from '../../core/http.js';
+import { sanitizeText } from '../../core/text.js';
+/** Bytes of HTML read to find the <title> (it lives in <head>). */
+const MAX_HTML_BYTES = 512 * 1024;
+const ENTITIES = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+    nbsp: ' ',
+};
+function decodeEntities(s) {
+    return s.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (m, e) => {
+        if (e[0] === '#') {
+            const code = e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10);
+            return Number.isFinite(code) && code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : m;
+        }
+        return ENTITIES[e.toLowerCase()] ?? m;
+    });
+}
+/** Extract the <title> text from (untrusted) HTML: entities decoded, sanitized, ≤80 chars. */
 export function extractTitle(html) {
     const m = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
-    return m ? m[1].replace(/\s+/g, ' ').trim().slice(0, 80) : '';
+    return m ? sanitizeText(decodeEntities(m[1]), 80) : '';
 }
 /** Map an HTTP status to NPC status: 2xx/3xx ok, 4xx/timeout warn, 5xx/refused crit. */
 export function statusFromHttp(code, timedOut = false) {
@@ -15,17 +36,15 @@ export function statusFromHttp(code, timedOut = false) {
 }
 /** Fetch a page and extract HTTP status + <title> (basic, no browser). */
 export async function basicCheck(url, timeoutMs = 8000) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
         const res = await fetch(url, {
-            signal: controller.signal,
-            headers: { 'User-Agent': 'nocville-npc' },
+            signal: AbortSignal.timeout(timeoutMs),
+            headers: { 'User-Agent': NPC_USER_AGENT },
             redirect: 'follow',
         });
         let title = '';
         try {
-            title = extractTitle(await res.text());
+            title = extractTitle((await readTextCapped(res, MAX_HTML_BYTES)).text);
         }
         catch {
             // body unavailable; leave title blank
@@ -33,20 +52,17 @@ export async function basicCheck(url, timeoutMs = 8000) {
         return { status: res.status, title, ok: res.ok, timedOut: false };
     }
     catch (err) {
-        const timedOut = err instanceof Error && err.name === 'AbortError';
+        const timedOut = err instanceof Error && (err.name === 'TimeoutError' || err.name === 'AbortError');
         return { status: 0, title: '', ok: false, timedOut };
     }
-    finally {
-        clearTimeout(timer);
-    }
 }
-/** Best-effort hostname for a URL, falling back to the raw string. */
+/** Hostname of a URL for labels and service ids (never credentials or path). */
 export function hostnameOf(url) {
     try {
-        return new URL(url).hostname;
+        return new URL(url).hostname || 'page';
     }
     catch {
-        return url.slice(0, 40);
+        return 'invalid-url';
     }
 }
 //# sourceMappingURL=basic-mode.js.map

package/dist/npcs/web-page-watcher/capture.d.ts

@@ -17,6 +17,10 @@ export interface PuppeteerPage {
         fullPage?: boolean;
     }): Promise<Buffer | Uint8Array>;
     close(): Promise<void>;
+    /** Used to dismiss JS dialogs, which would otherwise stall the capture. */
+    on?(event: 'dialog', cb: (dialog: {
+        dismiss(): Promise<void>;
+    }) => void): unknown;
 }
 export interface PuppeteerBrowser {
     newPage(): Promise<PuppeteerPage>;
@@ -38,6 +42,20 @@ export interface PuppeteerModule {
  * platform-specific known locations (mac app bundles; `which` on linux).
  */
 export declare function findChrome(explicit?: string): string | null;
+/**
+ * Chrome launch flags. The watched page is untrusted content, so Chrome's
+ * sandbox stays on unless it can't work: as root on Linux (Chrome refuses to
+ * start sandboxed, typical in containers) or when explicitly disabled.
+ */
+export declare function chromeArgs(opts: {
+    sandbox: boolean;
+    isRoot: boolean;
+}): {
+    args: string[];
+    sandboxed: boolean;
+};
+/** True when this process runs as root (POSIX only). */
+export declare function runningAsRoot(): boolean;
 /**
  * Load the optional `puppeteer-core` peer dependency without a static import,
  * so the package builds and runs when it isn't installed. Returns null if the

package/dist/npcs/web-page-watcher/capture.js

@@ -16,7 +16,11 @@ const LINUX_BINARIES = [
 ];
 function which(bin) {
     try {
-        const out = execFileSync('which', [bin], { encoding: 'utf-8' }).trim();
+        const out = execFileSync('which', [bin], {
+            encoding: 'utf-8',
+            timeout: 2000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
         return out || null;
     }
     catch {
@@ -49,6 +53,22 @@ export function findChrome(explicit) {
     }
     return null;
 }
+/**
+ * Chrome launch flags. The watched page is untrusted content, so Chrome's
+ * sandbox stays on unless it can't work: as root on Linux (Chrome refuses to
+ * start sandboxed, typical in containers) or when explicitly disabled.
+ */
+export function chromeArgs(opts) {
+    const args = ['--disable-gpu', '--hide-scrollbars', '--mute-audio', '--no-first-run'];
+    const sandboxed = opts.sandbox && !opts.isRoot;
+    if (!sandboxed)
+        args.push('--no-sandbox', '--disable-setuid-sandbox');
+    return { args, sandboxed };
+}
+/** True when this process runs as root (POSIX only). */
+export function runningAsRoot() {
+    return typeof process.getuid === 'function' && process.getuid() === 0;
+}
 /**
  * Load the optional `puppeteer-core` peer dependency without a static import,
  * so the package builds and runs when it isn't installed. Returns null if the

package/dist/npcs/web-page-watcher/defaults.d.ts

@@ -2,6 +2,10 @@ export declare const DEFAULTS: {
     pollInterval: number;
     minPollInterval: number;
     navTimeoutMs: number;
+    /** Extra time for screenshot + encode before a capture counts as hung. */
+    captureGraceMs: number;
+    /** Wait before relaunching Chrome after it failed to start. */
+    relaunchBackoffMs: number;
     maxColors: number;
     /** Polls to keep the 'changed' sub-status active after a page change. */
     changedPolls: number;
@@ -10,10 +14,29 @@ export declare const DEFAULTS: {
     scaleDivisor: number;
     waitUntil: string;
 };
+/**
+ * Size limits. The pixel payload is base64(W×H) and the API caps a screen value
+ * at 220 KB, so W×H must stay under ~165k; 320×240 leaves headroom. The
+ * viewport bound keeps Chrome's raster (and the PNG decode) to sane memory.
+ */
+export declare const LIMITS: {
+    screenMin: number;
+    screenMaxSide: number;
+    screenMaxPixels: number;
+    viewportMin: number;
+    viewportMax: number;
+};
 export type WatchMode = 'auto' | 'screenshot' | 'basic';
+export declare const WATCH_MODES: readonly WatchMode[];
+/** puppeteer `waitUntil` values. */
+export declare const WAIT_UNTIL: readonly ["load", "domcontentloaded", "networkidle0", "networkidle2"];
 /** Parse a "WxH" string into a {width, height} pair, or null if malformed. */
 export declare function parseDimensions(s: string): {
     width: number;
     height: number;
 } | null;
+/** Why a TV resolution is unusable, or null when it is fine. */
+export declare function screenSizeProblem(w: number, h: number): string | null;
+/** Why a browser viewport is unusable, or null when it is fine. */
+export declare function viewportProblem(w: number, h: number): string | null;
 //# sourceMappingURL=defaults.d.ts.map