@nocville/npc 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,234 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebPageWatcherNPC = void 0;
+const polling_npc_js_1 = require("../../core/polling-npc.js");
+const defaults_js_1 = require("./defaults.js");
+const pixelate_js_1 = require("./pixelate.js");
+const capture_js_1 = require("./capture.js");
+const basic_mode_js_1 = require("./basic-mode.js");
+class WebPageWatcherNPC extends polling_npc_js_1.PollingNPC {
+    url;
+    mode;
+    chromePath;
+    viewportW;
+    viewportH;
+    screenW;
+    screenH;
+    waitUntil;
+    puppeteer = null;
+    browser = null;
+    browserUnavailable = false;
+    chromeHintShown = false;
+    lastHash = 0;
+    changedPollsLeft = 0;
+    constructor(config) {
+        super({
+            ...config,
+            // Floor the poll interval — screenshots are expensive.
+            pollInterval: Math.max(config.pollInterval ?? defaults_js_1.DEFAULTS.pollInterval, defaults_js_1.DEFAULTS.minPollInterval),
+        });
+        this.url = config.url;
+        this.mode = config.mode ?? 'auto';
+        this.chromePath = config.chromePath;
+        this.screenW = config.screenWidth ?? defaults_js_1.DEFAULTS.screenW;
+        this.screenH = config.screenHeight ?? defaults_js_1.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_js_1.DEFAULTS.scaleDivisor;
+        this.viewportH = config.viewportHeight ?? this.screenH * defaults_js_1.DEFAULTS.scaleDivisor;
+        this.waitUntil = config.waitUntil ?? defaults_js_1.DEFAULTS.waitUntil;
+    }
+    get name() {
+        return 'web-page-watcher';
+    }
+    get defaultDisplayName() {
+        return (0, basic_mode_js_1.hostnameOf)(this.url);
+    }
+    get archetype() {
+        return 'custom';
+    }
+    get companion() {
+        return {
+            screenType: 'web-view',
+            size: { w: 4, h: 3 },
+            placement: 'adjacent-wall',
+            label: (0, basic_mode_js_1.hostnameOf)(this.url),
+        };
+    }
+    async collect() {
+        if (this.mode === 'basic')
+            return this.collectBasic();
+        const browser = await this.ensureBrowser();
+        if (!browser) {
+            // 'auto' silently degrades; explicit 'screenshot' warns once.
+            this.maybeShowChromeHint();
+            return this.collectBasic();
+        }
+        return this.collectScreenshot(browser);
+    }
+    async onStop() {
+        await super.onStop();
+        if (this.browser) {
+            try {
+                await this.browser.close();
+            }
+            catch {
+                // best effort
+            }
+            this.browser = null;
+        }
+    }
+    // --- Screenshot mode ---
+    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
+            // box-filters as a fallback if it doesn't.
+            await page.setViewport({
+                width: this.viewportW,
+                height: this.viewportH,
+                deviceScaleFactor: 0.125,
+            });
+            let httpStatus = 0;
+            let timedOut = false;
+            const loadStart = Date.now();
+            try {
+                const resp = await page.goto(this.url, {
+                    waitUntil: this.waitUntil,
+                    timeout: defaults_js_1.DEFAULTS.navTimeoutMs,
+                });
+                httpStatus = resp ? resp.status() : 0;
+            }
+            catch (err) {
+                timedOut = err instanceof Error && /timeout/i.test(err.message);
+            }
+            const loadMs = Date.now() - loadStart;
+            const captureStart = Date.now();
+            const shotRaw = await page.screenshot({ type: 'png' });
+            const shot = Buffer.isBuffer(shotRaw) ? shotRaw : Buffer.from(shotRaw);
+            const { screenData, byteSize, hash } = (0, pixelate_js_1.pngToPixelImage)(shot, defaults_js_1.DEFAULTS.maxColors, this.screenW, this.screenH);
+            const captureMs = Date.now() - captureStart;
+            const changed = this.lastHash !== 0 && hash !== this.lastHash;
+            this.lastHash = hash;
+            if (changed)
+                this.changedPollsLeft = defaults_js_1.DEFAULTS.changedPolls;
+            else if (this.changedPollsLeft > 0)
+                this.changedPollsLeft--;
+            const status = (0, basic_mode_js_1.statusFromHttp)(httpStatus, timedOut);
+            const host = (0, basic_mode_js_1.hostnameOf)(this.url);
+            const message = changed
+                ? 'Page updated!'
+                : httpStatus
+                    ? `${host} ${httpStatus < 400 ? 'OK' : 'ERR'} (${httpStatus}, ${loadMs}ms)`
+                    : `${host} unreachable`;
+            return {
+                status,
+                mood: moodFor(status),
+                message,
+                subStatus: this.changedPollsLeft > 0 ? 'changed' : undefined,
+                screenData,
+                metrics: {
+                    status_code: httpStatus,
+                    load_ms: loadMs,
+                    capture_ms: captureMs,
+                    frame_bytes: byteSize,
+                },
+            };
+        }
+        finally {
+            await page.close().catch(() => undefined);
+        }
+    }
+    async ensureBrowser() {
+        if (this.browserUnavailable)
+            return null;
+        if (this.browser && (0, capture_js_1.browserConnected)(this.browser))
+            return this.browser;
+        if (this.browser)
+            this.browser = null; // disconnected — relaunch
+        if (!this.puppeteer) {
+            this.puppeteer = await (0, capture_js_1.loadPuppeteer)();
+        }
+        const chromePath = (0, capture_js_1.findChrome)(this.chromePath);
+        if (!this.puppeteer || !chromePath) {
+            this.browserUnavailable = true;
+            return null;
+        }
+        try {
+            this.browser = await this.puppeteer.launch({
+                executablePath: chromePath,
+                headless: true,
+                args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-gpu', '--hide-scrollbars'],
+            });
+            this.browser.on('disconnected', () => {
+                this.browser = null;
+            });
+            return this.browser;
+        }
+        catch (err) {
+            this.logger.warn('Failed to launch Chrome', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            this.browserUnavailable = true;
+            return null;
+        }
+    }
+    maybeShowChromeHint() {
+        if (this.chromeHintShown)
+            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() {
+        const loadStart = Date.now();
+        const check = await (0, basic_mode_js_1.basicCheck)(this.url);
+        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 = (0, basic_mode_js_1.statusFromHttp)(check.status, check.timedOut);
+        if (status === 'healthy')
+            status = 'warning';
+        const host = (0, basic_mode_js_1.hostnameOf)(this.url);
+        const message = check.title ? `${host}: ${check.title}` : `${host} (${check.status || 'ERR'})`;
+        return {
+            status,
+            mood: moodFor(status),
+            message,
+            screenData: {
+                layout: 'ticker',
+                values: [
+                    { label: 'URL', value: 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',
+                    },
+                    { label: 'Title', value: check.title || '(no title)' },
+                    { label: 'Mode', value: 'basic' },
+                ],
+            },
+            metrics: { status_code: check.status, load_ms: loadMs, capture_ms: 0 },
+        };
+    }
+}
+exports.WebPageWatcherNPC = WebPageWatcherNPC;
+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/cjs/npcs/web-page-watcher/pixelate.js

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TARGET_H = exports.TARGET_W = void 0;
+exports.decodePng = decodePng;
+exports.boxDownscale = boxDownscale;
+exports.quantize = quantize;
+exports.buildPixelImageScreen = buildPixelImageScreen;
+exports.fnv1a = fnv1a;
+exports.pngToPixelImage = pngToPixelImage;
+const pngjs_1 = require("pngjs");
+/** Default target resolution for the web-view TV (4:3 to match a 4×3 companion). */
+exports.TARGET_W = 160;
+exports.TARGET_H = 120;
+/** Decode a PNG buffer to RGBA bytes + dimensions. */
+function decodePng(buf) {
+    const png = pngjs_1.PNG.sync.read(buf);
+    return { width: png.width, height: png.height, data: png.data };
+}
+/** Area-average (box filter) downscale of RGBA `src` to `tw`×`th`. */
+function boxDownscale(src, sw, sh, tw, th) {
+    const out = Buffer.alloc(tw * th * 4);
+    for (let ty = 0; ty < th; ty++) {
+        const sy0 = Math.floor((ty * sh) / th);
+        const sy1 = Math.max(sy0 + 1, Math.floor(((ty + 1) * sh) / th));
+        for (let tx = 0; tx < tw; tx++) {
+            const sx0 = Math.floor((tx * sw) / tw);
+            const sx1 = Math.max(sx0 + 1, Math.floor(((tx + 1) * sw) / tw));
+            let r = 0;
+            let g = 0;
+            let b = 0;
+            let n = 0;
+            for (let sy = sy0; sy < sy1; sy++) {
+                for (let sx = sx0; sx < sx1; sx++) {
+                    const i = (sy * sw + sx) * 4;
+                    r += src[i];
+                    g += src[i + 1];
+                    b += src[i + 2];
+                    n++;
+                }
+            }
+            const o = (ty * tw + tx) * 4;
+            out[o] = Math.round(r / n);
+            out[o + 1] = Math.round(g / n);
+            out[o + 2] = Math.round(b / n);
+            out[o + 3] = 255;
+        }
+    }
+    return out;
+}
+/**
+ * Median-cut quantization of RGBA pixels into at most `maxColors` colors.
+ * Returns a flat RGB palette and a per-pixel palette-index array. Each pixel's
+ * index is the box it lands in, so no separate nearest-color pass is needed.
+ */
+function quantize(rgba, pixelCount, maxColors) {
+    const pixels = new Array(pixelCount);
+    for (let i = 0; i < pixelCount; i++) {
+        const o = i * 4;
+        pixels[i] = { r: rgba[o], g: rgba[o + 1], b: rgba[o + 2] };
+    }
+    const refs = pixels.map((_, i) => i);
+    const boxes = [{ start: 0, end: refs.length }];
+    const widestChannel = (box) => {
+        let rmin = 255;
+        let rmax = 0;
+        let gmin = 255;
+        let gmax = 0;
+        let bmin = 255;
+        let bmax = 0;
+        for (let i = box.start; i < box.end; i++) {
+            const p = pixels[refs[i]];
+            if (p.r < rmin)
+                rmin = p.r;
+            if (p.r > rmax)
+                rmax = p.r;
+            if (p.g < gmin)
+                gmin = p.g;
+            if (p.g > gmax)
+                gmax = p.g;
+            if (p.b < bmin)
+                bmin = p.b;
+            if (p.b > bmax)
+                bmax = p.b;
+        }
+        const rr = rmax - rmin;
+        const gr = gmax - gmin;
+        const br = bmax - bmin;
+        if (rr >= gr && rr >= br)
+            return { channel: 'r', range: rr };
+        if (gr >= br)
+            return { channel: 'g', range: gr };
+        return { channel: 'b', range: br };
+    };
+    while (boxes.length < maxColors) {
+        let target = -1;
+        let best = 0;
+        for (let i = 0; i < boxes.length; i++) {
+            const box = boxes[i];
+            if (box.end - box.start < 2)
+                continue;
+            const { range } = widestChannel(box);
+            if (range > best) {
+                best = range;
+                target = i;
+            }
+        }
+        if (target < 0 || best <= 0)
+            break;
+        const box = boxes[target];
+        const { channel } = widestChannel(box);
+        const slice = refs
+            .slice(box.start, box.end)
+            .sort((a, b) => pixels[a][channel] - pixels[b][channel]);
+        for (let i = 0; i < slice.length; i++)
+            refs[box.start + i] = slice[i];
+        const mid = box.start + ((box.end - box.start) >> 1);
+        boxes.splice(target, 1, { start: box.start, end: mid }, { start: mid, end: box.end });
+    }
+    const palette = new Uint8Array(boxes.length * 3);
+    const indices = new Uint8Array(pixelCount);
+    boxes.forEach((box, bi) => {
+        let r = 0;
+        let g = 0;
+        let b = 0;
+        const n = box.end - box.start;
+        for (let i = box.start; i < box.end; i++) {
+            const ref = refs[i];
+            const p = pixels[ref];
+            r += p.r;
+            g += p.g;
+            b += p.b;
+            indices[ref] = bi;
+        }
+        palette[bi * 3] = Math.round(r / Math.max(1, n));
+        palette[bi * 3 + 1] = Math.round(g / Math.max(1, n));
+        palette[bi * 3 + 2] = Math.round(b / Math.max(1, n));
+    });
+    return { palette, indices };
+}
+/** Build a pixel-image screenData payload from a palette + index array. */
+function buildPixelImageScreen(width, height, palette, indices) {
+    const paletteCount = palette.length / 3;
+    return {
+        layout: 'pixel-image',
+        values: [
+            { label: 'fmt', value: `idx8;${width}x${height};p${paletteCount}` },
+            { label: 'palette', value: Buffer.from(palette).toString('base64') },
+            { label: 'pixels', value: Buffer.from(indices).toString('base64') },
+        ],
+    };
+}
+/** FNV-1a hash over bytes — cheap change detection for the rendered frame. */
+function fnv1a(bytes) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < bytes.length; i++) {
+        h ^= bytes[i];
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+/**
+ * Decode a PNG screenshot into a pixel-image screenData payload, downscaling to
+ * the target resolution if the source isn't already there (box-filter fallback
+ * for when Chrome's fractional deviceScaleFactor doesn't rasterize natively).
+ */
+function pngToPixelImage(pngBuffer, maxColors = 32, targetW = exports.TARGET_W, targetH = exports.TARGET_H) {
+    const { width, height, data } = decodePng(pngBuffer);
+    let rgba = data;
+    let w = width;
+    let h = height;
+    if (width !== targetW || height !== targetH) {
+        rgba = boxDownscale(data, width, height, targetW, targetH);
+        w = targetW;
+        h = targetH;
+    }
+    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) };
+}
+//# sourceMappingURL=pixelate.js.map

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map