@nocville/npc 0.2.2 → 0.2.3

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

@@ -2,6 +2,10 @@ export const DEFAULTS = {
     pollInterval: 60000, // 60s
     minPollInterval: 15000, // floor
     navTimeoutMs: 15000,
+    /** Extra time for screenshot + encode before a capture counts as hung. */
+    captureGraceMs: 15000,
+    /** Wait before relaunching Chrome after it failed to start. */
+    relaunchBackoffMs: 10 * 60 * 1000,
     maxColors: 32,
     /** Polls to keep the 'changed' sub-status active after a page change. */
     changedPolls: 2,
@@ -14,6 +18,21 @@ export const DEFAULTS = {
     scaleDivisor: 8,
     waitUntil: 'networkidle2',
 };
+/**
+ * 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 const LIMITS = {
+    screenMin: 16,
+    screenMaxSide: 320,
+    screenMaxPixels: 320 * 240,
+    viewportMin: 64,
+    viewportMax: 4096,
+};
+export const WATCH_MODES = ['auto', 'screenshot', 'basic'];
+/** puppeteer `waitUntil` values. */
+export const WAIT_UNTIL = ['load', 'domcontentloaded', 'networkidle0', 'networkidle2'];
 /** Parse a "WxH" string into a {width, height} pair, or null if malformed. */
 export function parseDimensions(s) {
     const m = s
@@ -22,6 +41,27 @@ export function parseDimensions(s) {
         .match(/^(\d+)x(\d+)$/);
     if (!m)
         return null;
-    return { width: parseInt(m[1], 10), height: parseInt(m[2], 10) };
+    const width = parseInt(m[1], 10);
+    const height = parseInt(m[2], 10);
+    return width > 0 && height > 0 ? { width, height } : null;
+}
+/** Why a TV resolution is unusable, or null when it is fine. */
+export function screenSizeProblem(w, h) {
+    const { screenMin, screenMaxSide, screenMaxPixels } = LIMITS;
+    if (!Number.isInteger(w) || !Number.isInteger(h) || w < screenMin || h < screenMin) {
+        return `--screen must be at least ${screenMin}x${screenMin}`;
+    }
+    if (w > screenMaxSide || h > screenMaxSide || w * h > screenMaxPixels) {
+        return `--screen must fit within ${screenMaxSide}x${screenMaxSide} and ${screenMaxPixels} pixels (e.g. 320x240)`;
+    }
+    return null;
+}
+/** Why a browser viewport is unusable, or null when it is fine. */
+export function viewportProblem(w, h) {
+    const { viewportMin, viewportMax } = LIMITS;
+    const ok = (n) => Number.isInteger(n) && n >= viewportMin && n <= viewportMax;
+    return ok(w) && ok(h)
+        ? null
+        : `--viewport sides must be between ${viewportMin} and ${viewportMax} pixels`;
 }
 //# sourceMappingURL=defaults.js.map

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

@@ -11,11 +11,18 @@ export interface WebPageWatcherConfig extends PollingNpcConfig {
     screenWidth?: number;
     screenHeight?: number;
     waitUntil?: string;
+    /**
+     * Run Chrome with its sandbox (default true). The sandbox is always off
+     * when running as root, where Chrome can't use it.
+     */
+    chromeSandbox?: boolean;
 }
 export declare class WebPageWatcherNPC extends PollingNPC {
     private url;
+    private host;
     private mode;
     private chromePath?;
+    private chromeSandbox;
     private viewportW;
     private viewportH;
     private screenW;
@@ -23,7 +30,10 @@ export declare class WebPageWatcherNPC extends PollingNPC {
     private waitUntil;
     private puppeteer;
     private browser;
-    private browserUnavailable;
+    /** puppeteer-core or Chrome is missing: never retried. */
+    private browserMissing;
+    /** Chrome failed to launch: retry after this time (epoch ms). */
+    private nextLaunchAttempt;
     private chromeHintShown;
     private lastHash;
     private changedPollsLeft;
@@ -34,9 +44,16 @@ export declare class WebPageWatcherNPC extends PollingNPC {
     get companion(): CompanionDecl;
     protected collect(): Promise<CollectedMetrics>;
     protected onStop(): Promise<void>;
+    private withDeadline;
     private collectScreenshot;
     private ensureBrowser;
+    private closeBrowser;
     private maybeShowChromeHint;
+    /**
+     * Plain fetch: HTTP status + page title on a ticker. When this is a fallback
+     * from screenshot mode (no Chrome), a healthy page is reported as a warning
+     * to nudge the Chrome setup; an explicit `--mode=basic` reports it healthy.
+     */
     private collectBasic;
 }
 //# sourceMappingURL=index.d.ts.map

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

@@ -1,12 +1,21 @@
 import { PollingNPC } from '../../core/polling-npc.js';
-import { DEFAULTS } from './defaults.js';
+import { moodForStatus } from '../../core/thresholds.js';
+import { statusColor } from '../../core/screen.js';
+import { NpcConfigError } from '../../core/errors.js';
+import { isHttpUrl } from '../../core/http.js';
+import { DEFAULTS, WATCH_MODES, WAIT_UNTIL, screenSizeProblem, viewportProblem, } from './defaults.js';
 import { pngToPixelImage } from './pixelate.js';
-import { findChrome, loadPuppeteer, browserConnected } from './capture.js';
+import { findChrome, loadPuppeteer, browserConnected, chromeArgs, runningAsRoot, } from './capture.js';
 import { basicCheck, statusFromHttp, hostnameOf } from './basic-mode.js';
+/** Thrown when a capture exceeds its deadline (the browser is then recycled). */
+class CaptureTimeout extends Error {
+}
 export class WebPageWatcherNPC extends PollingNPC {
     url;
+    host;
     mode;
     chromePath;
+    chromeSandbox;
     viewportW;
     viewportH;
     screenW;
@@ -14,7 +23,10 @@ export class WebPageWatcherNPC extends PollingNPC {
     waitUntil;
     puppeteer = null;
     browser = null;
-    browserUnavailable = false;
+    /** puppeteer-core or Chrome is missing: never retried. */
+    browserMissing = false;
+    /** Chrome failed to launch: retry after this time (epoch ms). */
+    nextLaunchAttempt = 0;
     chromeHintShown = false;
     lastHash = 0;
     changedPollsLeft = 0;
@@ -24,22 +36,41 @@ export class WebPageWatcherNPC extends PollingNPC {
             // Floor the poll interval — screenshots are expensive.
             pollInterval: Math.max(config.pollInterval ?? DEFAULTS.pollInterval, DEFAULTS.minPollInterval),
         });
+        // The page is rendered and shown to the whole office: http(s) only, never
+        // file:, data:, chrome: or javascript: URLs.
+        if (!isHttpUrl(config.url)) {
+            throw new NpcConfigError('--url must be an http(s) URL');
+        }
         this.url = config.url;
-        this.mode = config.mode ?? 'auto';
+        this.host = hostnameOf(config.url);
+        const mode = config.mode ?? 'auto';
+        if (!WATCH_MODES.includes(mode)) {
+            throw new NpcConfigError(`--mode must be one of ${WATCH_MODES.join(', ')}`);
+        }
+        this.mode = mode;
+        const waitUntil = config.waitUntil ?? DEFAULTS.waitUntil;
+        if (!WAIT_UNTIL.includes(waitUntil)) {
+            throw new NpcConfigError(`--wait-until must be one of ${WAIT_UNTIL.join(', ')}`);
+        }
+        this.waitUntil = waitUntil;
         this.chromePath = config.chromePath;
+        this.chromeSandbox = config.chromeSandbox ?? true;
         this.screenW = config.screenWidth ?? DEFAULTS.screenW;
         this.screenH = config.screenHeight ?? DEFAULTS.screenH;
         // Derive the viewport from the screen size for native downscaling unless the
         // user overrides it (in which case pngToPixelImage box-filters to screen).
         this.viewportW = config.viewportWidth ?? this.screenW * DEFAULTS.scaleDivisor;
         this.viewportH = config.viewportHeight ?? this.screenH * DEFAULTS.scaleDivisor;
-        this.waitUntil = config.waitUntil ?? DEFAULTS.waitUntil;
+        const sizeProblem = screenSizeProblem(this.screenW, this.screenH) ??
+            viewportProblem(this.viewportW, this.viewportH);
+        if (sizeProblem)
+            throw new NpcConfigError(sizeProblem);
     }
     get name() {
         return 'web-page-watcher';
     }
     get defaultDisplayName() {
-        return hostnameOf(this.url);
+        return this.host;
     }
     get archetype() {
         return 'custom';
@@ -49,43 +80,58 @@ export class WebPageWatcherNPC extends PollingNPC {
             screenType: 'web-view',
             size: { w: 4, h: 3 },
             placement: 'adjacent-wall',
-            label: hostnameOf(this.url),
+            label: this.host,
         };
     }
     async collect() {
         if (this.mode === 'basic')
-            return this.collectBasic();
+            return this.collectBasic(false);
         const browser = await this.ensureBrowser();
         if (!browser) {
-            // 'auto' silently degrades; explicit 'screenshot' warns once.
             this.maybeShowChromeHint();
-            return this.collectBasic();
+            return this.collectBasic(true);
+        }
+        try {
+            return await this.withDeadline(this.collectScreenshot(browser));
+        }
+        catch (err) {
+            if (this.state !== 'running')
+                throw err; // shutting down: nothing to report
+            // A crashed or wedged browser: recycle it and report this cycle from a plain fetch.
+            this.logger.warn('Screenshot failed; using a basic check this cycle', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            await this.closeBrowser();
+            return this.collectBasic(true);
         }
-        return this.collectScreenshot(browser);
     }
     async onStop() {
+        // Close Chrome first: it aborts an in-flight capture, so the base class
+        // doesn't wait out a slow page load before pushing offline.
+        await this.closeBrowser();
         await super.onStop();
-        if (this.browser) {
-            try {
-                await this.browser.close();
-            }
-            catch {
-                // best effort
-            }
-            this.browser = null;
-        }
     }
     // --- Screenshot mode ---
+    withDeadline(work) {
+        const ms = DEFAULTS.navTimeoutMs + DEFAULTS.captureGraceMs;
+        let timer;
+        const deadline = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new CaptureTimeout(`capture exceeded ${ms}ms`)), ms);
+        });
+        return Promise.race([work, deadline]).finally(() => clearTimeout(timer));
+    }
     async collectScreenshot(browser) {
         const page = await browser.newPage();
         try {
-            // deviceScaleFactor 0.125 makes Chrome rasterize the viewport down to the
-            // screen size natively (e.g. 1280×800 → 160×100); pngToPixelImage
+            // A page that alert()s would block navigation and the screenshot.
+            page.on?.('dialog', (dialog) => void dialog.dismiss().catch(() => undefined));
+            // deviceScaleFactor 1/8 makes Chrome rasterize the viewport down to the
+            // screen size natively (e.g. 1280×960 → 160×120); pngToPixelImage
             // box-filters as a fallback if it doesn't.
             await page.setViewport({
                 width: this.viewportW,
                 height: this.viewportH,
-                deviceScaleFactor: 0.125,
+                deviceScaleFactor: 1 / DEFAULTS.scaleDivisor,
             });
             let httpStatus = 0;
             let timedOut = false;
@@ -113,15 +159,14 @@ export class WebPageWatcherNPC extends PollingNPC {
             else if (this.changedPollsLeft > 0)
                 this.changedPollsLeft--;
             const status = statusFromHttp(httpStatus, timedOut);
-            const host = hostnameOf(this.url);
             const message = changed
                 ? 'Page updated!'
                 : httpStatus
-                    ? `${host} ${httpStatus < 400 ? 'OK' : 'ERR'} (${httpStatus}, ${loadMs}ms)`
-                    : `${host} unreachable`;
+                    ? `${this.host} ${httpStatus < 400 ? 'OK' : 'ERR'} (${httpStatus}, ${loadMs}ms)`
+                    : `${this.host} ${timedOut ? 'timed out' : 'unreachable'}`;
             return {
                 status,
-                mood: moodFor(status),
+                mood: moodForStatus(status),
                 message,
                 subStatus: this.changedPollsLeft > 0 ? 'changed' : undefined,
                 screenData,
@@ -138,74 +183,92 @@ export class WebPageWatcherNPC extends PollingNPC {
         }
     }
     async ensureBrowser() {
-        if (this.browserUnavailable)
+        if (this.browserMissing || Date.now() < this.nextLaunchAttempt)
             return null;
         if (this.browser && browserConnected(this.browser))
             return this.browser;
-        if (this.browser)
-            this.browser = null; // disconnected — relaunch
-        if (!this.puppeteer) {
-            this.puppeteer = await loadPuppeteer();
-        }
+        this.browser = null; // absent or disconnected — (re)launch
+        this.puppeteer ??= await loadPuppeteer();
         const chromePath = findChrome(this.chromePath);
         if (!this.puppeteer || !chromePath) {
-            this.browserUnavailable = true;
+            this.browserMissing = true;
             return null;
         }
+        const { args, sandboxed } = chromeArgs({
+            sandbox: this.chromeSandbox,
+            isRoot: runningAsRoot(),
+        });
+        if (!sandboxed) {
+            this.logger.warn('Chrome sandbox disabled' +
+                (this.chromeSandbox ? ' (running as root)' : '') +
+                ': only watch pages you trust');
+        }
         try {
-            this.browser = await this.puppeteer.launch({
+            const browser = await this.puppeteer.launch({
                 executablePath: chromePath,
                 headless: true,
-                args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-gpu', '--hide-scrollbars'],
+                args,
             });
-            this.browser.on('disconnected', () => {
-                this.browser = null;
+            browser.on('disconnected', () => {
+                if (this.browser === browser)
+                    this.browser = null;
             });
-            return this.browser;
+            // Stopped while Chrome was starting: don't leave it running.
+            if (this.state !== 'running') {
+                await browser.close().catch(() => undefined);
+                return null;
+            }
+            this.browser = browser;
+            return browser;
         }
         catch (err) {
-            this.logger.warn('Failed to launch Chrome', {
+            this.logger.warn('Failed to launch Chrome; retrying in 10 minutes', {
                 error: err instanceof Error ? err.message : String(err),
             });
-            this.browserUnavailable = true;
+            this.nextLaunchAttempt = Date.now() + DEFAULTS.relaunchBackoffMs;
             return null;
         }
     }
+    async closeBrowser() {
+        const browser = this.browser;
+        this.browser = null;
+        if (browser)
+            await browser.close().catch(() => undefined);
+    }
     maybeShowChromeHint() {
-        if (this.chromeHintShown)
+        if (this.chromeHintShown || !this.browserMissing)
             return;
         this.chromeHintShown = true;
         this.logger.warn('Chrome/puppeteer-core unavailable — falling back to basic mode. ' +
             'Install `puppeteer-core` and Google Chrome (or set --chrome-path/CHROME_PATH) for the pixel-art TV.');
     }
     // --- Basic mode ---
-    async collectBasic() {
+    /**
+     * Plain fetch: HTTP status + page title on a ticker. When this is a fallback
+     * from screenshot mode (no Chrome), a healthy page is reported as a warning
+     * to nudge the Chrome setup; an explicit `--mode=basic` reports it healthy.
+     */
+    async collectBasic(fallback) {
         const loadStart = Date.now();
-        const check = await basicCheck(this.url);
+        const check = await basicCheck(this.url, DEFAULTS.navTimeoutMs);
         const loadMs = Date.now() - loadStart;
-        // Basic mode can't render the pixel TV, so it never reports fully healthy —
-        // a healthy HTTP result is downgraded to a warning to nudge Chrome setup.
-        let status = statusFromHttp(check.status, check.timedOut);
-        if (status === 'healthy')
-            status = 'warning';
-        const host = hostnameOf(this.url);
-        const message = check.title ? `${host}: ${check.title}` : `${host} (${check.status || 'ERR'})`;
+        const httpStatus = statusFromHttp(check.status, check.timedOut);
+        const status = fallback && httpStatus === 'healthy' ? 'warning' : httpStatus;
+        const message = check.title
+            ? `${this.host}: ${check.title}`
+            : `${this.host} (${check.status || (check.timedOut ? 'timed out' : 'ERR')})`;
         return {
             status,
-            mood: moodFor(status),
+            mood: moodForStatus(status),
             message,
             screenData: {
                 layout: 'ticker',
                 values: [
-                    { label: 'URL', value: host },
+                    { label: 'URL', value: this.host },
                     {
                         label: 'HTTP',
                         value: check.status ? String(check.status) : 'ERR',
-                        color: check.status >= 200 && check.status < 400
-                            ? 'green'
-                            : check.status >= 500 || check.status === 0
-                                ? 'red'
-                                : 'amber',
+                        color: statusColor(httpStatus),
                     },
                     { label: 'Title', value: check.title || '(no title)' },
                     { label: 'Mode', value: 'basic' },
@@ -215,16 +278,4 @@ export class WebPageWatcherNPC extends PollingNPC {
         };
     }
 }
-function moodFor(status) {
-    switch (status) {
-        case 'healthy':
-            return 'happy';
-        case 'warning':
-            return 'concerned';
-        case 'critical':
-            return 'stressed';
-        default:
-            return 'idle';
-    }
-}
 //# sourceMappingURL=index.js.map

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

@@ -167,6 +167,7 @@ export function pngToPixelImage(pngBuffer, maxColors = 32, targetW = TARGET_W, t
     const { palette, indices } = quantize(rgba, w * h, maxColors);
     const screenData = buildPixelImageScreen(w, h, palette, indices);
     const byteSize = screenData.values.reduce((sum, v) => sum + v.value.length, 0);
-    return { screenData, byteSize, hash: fnv1a(indices) };
+    // Hash the palette too: a recolour with the same layout is still a change.
+    return { screenData, byteSize, hash: fnv1a(Buffer.concat([palette, indices])) };
 }
 //# sourceMappingURL=pixelate.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocville/npc",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Put your Claude Code and Codex sessions (and your servers) in the Nocville office as live NPCs",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,7 +24,7 @@
   ],
   "dependencies": {
     "pngjs": "^7.0.0",
-    "@nocville/node": "^0.2.2"
+    "@nocville/node": "^0.2.3"
   },
   "peerDependencies": {
     "puppeteer-core": "*"