@nocville/npc 0.0.0-stage → 0.2.1

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

@@ -0,0 +1,230 @@
+import { PollingNPC } from '../../core/polling-npc.js';
+import { DEFAULTS } from './defaults.js';
+import { pngToPixelImage } from './pixelate.js';
+import { findChrome, loadPuppeteer, browserConnected } from './capture.js';
+import { basicCheck, statusFromHttp, hostnameOf } from './basic-mode.js';
+export class WebPageWatcherNPC extends 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.pollInterval, DEFAULTS.minPollInterval),
+        });
+        this.url = config.url;
+        this.mode = config.mode ?? 'auto';
+        this.chromePath = config.chromePath;
+        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;
+    }
+    get name() {
+        return 'web-page-watcher';
+    }
+    get defaultDisplayName() {
+        return hostnameOf(this.url);
+    }
+    get archetype() {
+        return 'custom';
+    }
+    get companion() {
+        return {
+            screenType: 'web-view',
+            size: { w: 4, h: 3 },
+            placement: 'adjacent-wall',
+            label: 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.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 } = pngToPixelImage(shot, 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.changedPolls;
+            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`;
+            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 && browserConnected(this.browser))
+            return this.browser;
+        if (this.browser)
+            this.browser = null; // disconnected — relaunch
+        if (!this.puppeteer) {
+            this.puppeteer = await loadPuppeteer();
+        }
+        const chromePath = 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 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 = 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'})`;
+        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 },
+        };
+    }
+}
+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.d.ts

@@ -0,0 +1,36 @@
+import type { ScreenData } from '../../core/types.js';
+/** Default target resolution for the web-view TV (4:3 to match a 4×3 companion). */
+export declare const TARGET_W = 160;
+export declare const TARGET_H = 120;
+/** Decode a PNG buffer to RGBA bytes + dimensions. */
+export declare function decodePng(buf: Buffer): {
+    width: number;
+    height: number;
+    data: Buffer;
+};
+/** Area-average (box filter) downscale of RGBA `src` to `tw`×`th`. */
+export declare function boxDownscale(src: Buffer, sw: number, sh: number, tw: number, th: number): Buffer;
+/**
+ * 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.
+ */
+export declare function quantize(rgba: Buffer, pixelCount: number, maxColors: number): {
+    palette: Uint8Array;
+    indices: Uint8Array;
+};
+/** Build a pixel-image screenData payload from a palette + index array. */
+export declare function buildPixelImageScreen(width: number, height: number, palette: Uint8Array, indices: Uint8Array): ScreenData;
+/** FNV-1a hash over bytes — cheap change detection for the rendered frame. */
+export declare function fnv1a(bytes: Uint8Array): number;
+/**
+ * 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).
+ */
+export declare function pngToPixelImage(pngBuffer: Buffer, maxColors?: number, targetW?: number, targetH?: number): {
+    screenData: ScreenData;
+    byteSize: number;
+    hash: number;
+};
+//# sourceMappingURL=pixelate.d.ts.map

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

@@ -0,0 +1,172 @@
+import { PNG } from 'pngjs';
+/** Default target resolution for the web-view TV (4:3 to match a 4×3 companion). */
+export const TARGET_W = 160;
+export const TARGET_H = 120;
+/** Decode a PNG buffer to RGBA bytes + dimensions. */
+export function decodePng(buf) {
+    const png = 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`. */
+export 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.
+ */
+export 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. */
+export 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. */
+export 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).
+ */
+export function pngToPixelImage(pngBuffer, maxColors = 32, targetW = TARGET_W, targetH = 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/package.json

@@ -1,6 +1,76 @@
 {
   "name": "@nocville/npc",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.1",
+  "description": "Put your Claude Code and Codex sessions (and your servers) in the Nocville office as live NPCs",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "nocville-npc": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "pngjs": "^7.0.0",
+    "@nocville/node": "^0.2.1"
+  },
+  "peerDependencies": {
+    "puppeteer-core": "*"
+  },
+  "peerDependenciesMeta": {
+    "puppeteer-core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@types/pngjs": "^6.0.5",
+    "typescript": "^5.3.2",
+    "vitest": "^3.2.6",
+    "puppeteer-core": "^24.0.0"
+  },
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "nocville",
+    "claude-code",
+    "codex",
+    "ai-agents",
+    "monitoring",
+    "npc",
+    "status",
+    "cli"
+  ],
+  "license": "MIT",
+  "homepage": "https://nocville.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marshmansf/nocville.git",
+    "directory": "libs/nocville-npc-library"
+  },
+  "scripts": {
+    "build": "tsc && tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({ type: 'commonjs' }))\" && node -e \"require('fs').chmodSync('dist/cli.js', 0o755)\"",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "smoke": "node scripts/smoke.mjs",
+    "simulate": "node scripts/simulate.mjs"
+  }
 }