@nocville/npc 0.2.1 → 0.2.3

package/dist/cli.js

@@ -2,7 +2,8 @@
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
-import { parseArgs, resolveConfig, stringFlag, numberFlag, boolFlag } from './core/config.js';
+import { parseArgs, resolveConfig, stringFlag, numberFlag, boolFlag, listFlag, } from './core/config.js';
+import { NpcConfigError } from './core/errors.js';
 import { Logger } from './core/logger.js';
 import { ensureSessionFilterTemplate, loadSessionFilter, sessionPublishDecision, } from './core/session-filter.js';
 // NPC modules are imported lazily per command: `claude-code hook` / `codex hook`
@@ -77,17 +78,23 @@ Internet Connectivity Options:
   --poll-interval=<ms>    Poll interval in ms (default: 30000)
   --dns-hosts=<list>      Comma-separated DNS hosts (default: google.com,cloudflare.com)
   --http-urls=<list>      Comma-separated HTTP URLs to check
-  --latency-hosts=<list>  Comma-separated hosts for latency checks
+  --latency-hosts=<list>  Comma-separated TCP latency targets: host, host:port or
+                          [ipv6]:port (default: 8.8.8.8:443,1.1.1.1:443;
+                          port 80 when omitted)
   --slow-threshold=<ms>   Slow response threshold in ms (default: 1000)
+  --timeout=<ms>          Per-check timeout in ms (default: 5000)
 
 Process Watcher Options:
   --poll-interval=<ms>    Poll interval in ms (default: 15000)
-  --processes=<list>      Comma-separated process names to watch
+  --processes=<list>      Comma-separated executable names to watch (python
+                          also matches python3.11; a /path matches exactly)
   --cpu-warn=<n>          CPU warning threshold % (default: 80)
   --mem-warn=<n>          Memory warning threshold MB (default: 500)
 
 Log Watcher Options:
-  --files=<list>          Comma-separated log file paths
+  --files=<list>          Comma-separated log file paths (followed across
+                          rotation; files may appear later). Lines shown on
+                          the screen have secrets redacted.
   --error-pattern=<regex> Error pattern (default: ERROR|FATAL)
   --warning-pattern=<regex> Warning pattern (default: WARN)
   --window=<seconds>      Sliding window in seconds (default: 300)
@@ -98,23 +105,30 @@ Log Watcher Options:
 Receptionist Options:
   --poll-interval=<ms>    Clock tick in ms (default: 60000)
   --lat=<n> --lon=<n>     Explicit coordinates for weather
-  --location=<name>       Place name to geocode (else IP geo)
+  --location=<name>       Place name to geocode (open-meteo)
+  --no-ip-geo             Without --lat/--lon or --location, don't look up
+                          this machine's IP location (ipapi.co); show time only
   --fahrenheit            Show temperature in °F (default: °C)
 
 GitHub Watcher Options:
   --repo=<owner/name>     Repository to watch (required)
   --branch=<name>         Branch to watch (default: repo default branch)
-  --token=<token>         GitHub token (or GITHUB_TOKEN env)
-  --poll-interval=<ms>    Poll interval in ms (default: 60000)
+  --token=<token>         GitHub token (prefer the GITHUB_TOKEN env: flags are
+                          visible in the process list)
+  --poll-interval=<ms>    Poll interval in ms (default: 60000 with a token,
+                          90000 without, to stay under GitHub's 60/hour)
 
 Web Page Watcher Options:
-  --url=<url>             Page to watch (required)
+  --url=<url>             http(s) page to watch (required)
   --mode=<auto|screenshot|basic>  Render mode (default: auto)
   --interval=<ms>         Poll interval in ms (default: 60000, floor 15000)
-  --viewport=<WxH>        Browser viewport (default: screen x 8)
-  --screen=<WxH>          TV pixel resolution (default: 160x120; e.g. 160x100)
-  --wait-until=<event>    Puppeteer waitUntil (default: networkidle2)
+  --viewport=<WxH>        Browser viewport (default: screen x 8, max 4096x4096)
+  --screen=<WxH>          TV pixel resolution (default: 160x120, max 320x240)
+  --wait-until=<event>    load, domcontentloaded, networkidle0 or networkidle2
+                          (default: networkidle2)
   --chrome-path=<path>    Chrome executable (or CHROME_PATH env)
+  --no-chrome-sandbox     Run Chrome without its sandbox (only for trusted
+                          pages; automatic when running as root)
   (needs puppeteer-core + Chrome for the pixel-art TV; falls back to basic)
 `.trim();
 async function main() {
@@ -275,18 +289,10 @@ async function main() {
             if (!config.serviceId) {
                 config.serviceId = 'internet-connectivity';
             }
-            const dnsHosts = stringFlag(parsed.flags, 'dns-hosts')?.split(',');
-            const httpUrls = stringFlag(parsed.flags, 'http-urls')?.split(',');
-            const latencyHostsRaw = stringFlag(parsed.flags, 'latency-hosts')?.split(',');
-            const latencyHosts = latencyHostsRaw?.map((h) => ({ host: h.trim(), port: 80 }));
             const { InternetConnectivityNPC } = await import('./npcs/internet-connectivity/index.js');
             const npc = new InternetConnectivityNPC({
                 ...config,
-                pollInterval: numberFlag(parsed.flags, 'poll-interval'),
-                dnsHosts,
-                httpUrls,
-                latencyHosts,
-                slowThreshold: numberFlag(parsed.flags, 'slow-threshold'),
+                ...InternetConnectivityNPC.configFromFlags(parsed.flags),
             });
             logger.info('Starting internet-connectivity NPC');
             await npc.start();
@@ -296,8 +302,8 @@ async function main() {
             if (!config.serviceId) {
                 config.serviceId = 'process-watcher';
             }
-            const processesStr = stringFlag(parsed.flags, 'processes');
-            if (!processesStr) {
+            const processes = listFlag(parsed.flags, 'processes');
+            if (!processes) {
                 console.error('Error: --processes is required (comma-separated list)');
                 process.exit(1);
             }
@@ -305,7 +311,7 @@ async function main() {
             const npc = new ProcessWatcherNPC({
                 ...config,
                 pollInterval: numberFlag(parsed.flags, 'poll-interval'),
-                processes: processesStr.split(','),
+                processes,
                 cpuWarn: numberFlag(parsed.flags, 'cpu-warn'),
                 memWarn: numberFlag(parsed.flags, 'mem-warn'),
             });
@@ -314,8 +320,8 @@ async function main() {
             break;
         }
         case 'log-watcher': {
-            const filesStr = stringFlag(parsed.flags, 'files');
-            if (!filesStr) {
+            const files = listFlag(parsed.flags, 'files');
+            if (!files) {
                 console.error('Error: --files is required (comma-separated list)');
                 process.exit(1);
             }
@@ -325,7 +331,7 @@ async function main() {
             const { LogWatcherNPC } = await import('./npcs/log-watcher/index.js');
             const npc = new LogWatcherNPC({
                 ...config,
-                files: filesStr.split(','),
+                files,
                 errorPattern: stringFlag(parsed.flags, 'error-pattern'),
                 warningPattern: stringFlag(parsed.flags, 'warning-pattern'),
                 windowSeconds: numberFlag(parsed.flags, 'window'),
@@ -349,6 +355,7 @@ async function main() {
                 lon: numberFlag(parsed.flags, 'lon'),
                 location: stringFlag(parsed.flags, 'location'),
                 fahrenheit: boolFlag(parsed.flags, 'fahrenheit') ?? false,
+                ipGeo: boolFlag(parsed.flags, 'no-ip-geo') !== true,
             });
             logger.info('Starting receptionist NPC');
             await npc.start();
@@ -365,11 +372,15 @@ async function main() {
                 config.serviceId = `github-${shortName.replace(/[^a-zA-Z0-9_-]/g, '-')}`.slice(0, 100);
             }
             const { GitHubWatcherNPC } = await import('./npcs/github-watcher/index.js');
+            const tokenFlag = stringFlag(parsed.flags, 'token');
+            if (tokenFlag) {
+                logger.warn('--token is visible to other local users in the process list; prefer GITHUB_TOKEN');
+            }
             const npc = new GitHubWatcherNPC({
                 ...config,
                 repo,
                 branch: stringFlag(parsed.flags, 'branch'),
-                token: stringFlag(parsed.flags, 'token') ?? process.env['GITHUB_TOKEN'],
+                token: tokenFlag ?? process.env['GITHUB_TOKEN'],
                 pollInterval: numberFlag(parsed.flags, 'poll-interval'),
             });
             logger.info('Starting github-watcher NPC');
@@ -385,22 +396,28 @@ async function main() {
             const { hostnameOf } = await import('./npcs/web-page-watcher/basic-mode.js');
             const { parseDimensions } = await import('./npcs/web-page-watcher/defaults.js');
             const { WebPageWatcherNPC } = await import('./npcs/web-page-watcher/index.js');
-            const parseWxH = (v) => v ? (parseDimensions(v) ?? undefined) : undefined;
+            const parseWxH = (flag) => {
+                const v = stringFlag(parsed.flags, flag);
+                if (v === undefined)
+                    return undefined;
+                const dims = parseDimensions(v);
+                if (!dims)
+                    throw new NpcConfigError(`--${flag} must look like 160x120`);
+                return dims;
+            };
             if (!config.serviceId) {
                 config.serviceId = `webpage-${hostnameOf(url)}`
                     .replace(/[^a-zA-Z0-9_.-]/g, '-')
                     .slice(0, 100);
             }
-            const modeFlag = stringFlag(parsed.flags, 'mode');
-            const mode = modeFlag === 'auto' || modeFlag === 'screenshot' || modeFlag === 'basic'
-                ? modeFlag
-                : undefined;
-            const viewport = parseWxH(stringFlag(parsed.flags, 'viewport'));
-            const screen = parseWxH(stringFlag(parsed.flags, 'screen'));
+            const viewport = parseWxH('viewport');
+            const screen = parseWxH('screen');
             const npc = new WebPageWatcherNPC({
                 ...config,
                 url,
-                mode,
+                // Validated (with a clear error) by the constructor.
+                mode: stringFlag(parsed.flags, 'mode'),
+                chromeSandbox: boolFlag(parsed.flags, 'no-chrome-sandbox') !== true,
                 chromePath: stringFlag(parsed.flags, 'chrome-path'),
                 waitUntil: stringFlag(parsed.flags, 'wait-until'),
                 viewportWidth: viewport?.width,
@@ -543,6 +560,10 @@ main().catch((err) => {
         process.stdout.write('{}\n');
         return;
     }
+    if (err instanceof NpcConfigError) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
     console.error('Fatal error:', err);
     process.exit(1);
 });

package/dist/core/base-npc.d.ts

@@ -20,6 +20,11 @@ export declare abstract class BaseNPC {
     protected get defaultDisplayName(): string | null;
     /** The banner name to send, clamped to the API's 32-char limit, or undefined. */
     private pushName;
+    /**
+     * NPC type sent as the push `kind` (groups NPCs for per-type rules such as "all process
+     * watchers work in the Server Room"). Defaults to `name` when it is a valid slug.
+     */
+    get kind(): string | undefined;
     /** NPC archetype — steers movement speed and default behavior. Override per NPC. */
     get archetype(): Archetype;
     /** Base behavior hints sent on every push (merged with per-cycle overrides). */

package/dist/core/base-npc.js

@@ -39,6 +39,13 @@ export class BaseNPC {
         const name = this.displayName;
         return name ? truncate(name, 32) : undefined;
     }
+    /**
+     * NPC type sent as the push `kind` (groups NPCs for per-type rules such as "all process
+     * watchers work in the Server Room"). Defaults to `name` when it is a valid slug.
+     */
+    get kind() {
+        return /^[a-z0-9][a-z0-9-]{0,39}$/.test(this.name) ? this.name : undefined;
+    }
     /** NPC archetype — steers movement speed and default behavior. Override per NPC. */
     get archetype() {
         return 'service';
@@ -113,6 +120,7 @@ export class BaseNPC {
             message: metrics.message ? truncate(metrics.message, 500) : undefined,
             metrics: metrics.metrics,
             archetype: this.archetype,
+            kind: this.kind,
             subStatus: metrics.subStatus,
             screenData: metrics.screenData,
             behavior: Object.keys(behavior).length > 0 ? behavior : undefined,

package/dist/core/config.d.ts

@@ -18,5 +18,10 @@ export declare function parseArgs(argv: string[]): ParsedArgs;
 export declare function resolveConfig(flags: Record<string, string | boolean>, overrides?: Partial<NpcConfig>): NpcConfig;
 export declare function stringFlag(flags: Record<string, string | boolean>, key: string): string | undefined;
 export declare function boolFlag(flags: Record<string, string | boolean>, key: string): boolean | undefined;
+/**
+ * A comma-separated list flag (`--processes=nginx,redis`): entries trimmed,
+ * empties dropped, duplicates removed. Undefined when the flag is absent or empty.
+ */
+export declare function listFlag(flags: Record<string, string | boolean>, key: string): string[] | undefined;
 export declare function numberFlag(flags: Record<string, string | boolean>, key: string): number | undefined;
 //# sourceMappingURL=config.d.ts.map

package/dist/core/config.js

@@ -89,11 +89,27 @@ export function boolFlag(flags, key) {
         return false;
     return undefined;
 }
+/**
+ * A comma-separated list flag (`--processes=nginx,redis`): entries trimmed,
+ * empties dropped, duplicates removed. Undefined when the flag is absent or empty.
+ */
+export function listFlag(flags, key) {
+    const raw = stringFlag(flags, key);
+    if (raw === undefined)
+        return undefined;
+    const items = [
+        ...new Set(raw
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean)),
+    ];
+    return items.length > 0 ? items : undefined;
+}
 export function numberFlag(flags, key) {
     const val = flags[key];
-    if (typeof val === 'string') {
+    if (typeof val === 'string' && val.trim() !== '') {
         const n = Number(val);
-        if (!Number.isNaN(n))
+        if (Number.isFinite(n))
             return n;
     }
     return undefined;

package/dist/core/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A user-facing configuration problem (bad flag value, unsupported platform).
+ * The CLI prints only its message and exits 1 — no stack trace — so throw it
+ * for anything the user can fix by changing how they run the NPC.
+ */
+export declare class NpcConfigError extends Error {
+    constructor(message: string);
+}
+/** Throw an NpcConfigError on Windows, for NPCs that rely on POSIX tools or paths. */
+export declare function assertPosix(npcName: string, hint: string): void;
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.js

@@ -0,0 +1,18 @@
+/**
+ * A user-facing configuration problem (bad flag value, unsupported platform).
+ * The CLI prints only its message and exits 1 — no stack trace — so throw it
+ * for anything the user can fix by changing how they run the NPC.
+ */
+export class NpcConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NpcConfigError';
+    }
+}
+/** Throw an NpcConfigError on Windows, for NPCs that rely on POSIX tools or paths. */
+export function assertPosix(npcName, hint) {
+    if (process.platform === 'win32') {
+        throw new NpcConfigError(`${npcName} is not supported on Windows. ${hint}`);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/http.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Small, bounded HTTP helpers for NPCs that read untrusted remote content
+ * (weather/geo APIs, GitHub, watched web pages). Every call has a timeout and
+ * every body read has a byte cap, so a slow or hostile server can neither hang
+ * a collection nor balloon memory.
+ */
+/** The `User-Agent` sent by every NPC request. */
+export declare const NPC_USER_AGENT = "nocville-npc";
+/** Default cap for a response body read into memory. */
+export declare const DEFAULT_MAX_BODY_BYTES: number;
+/** True for an absolute http(s) URL (anything else — file:, data:, javascript: — is refused). */
+export declare function isHttpUrl(value: string): boolean;
+/** A URL rendered for logs/screens: scheme, host and path only — never credentials or query. */
+export declare function displayUrl(value: string): string;
+/** The minimal response surface the helpers read (global fetch satisfies it). */
+export interface ReadableResponse {
+    headers?: {
+        get(name: string): string | null;
+    };
+    body?: ReadableStream<Uint8Array> | null;
+    text(): Promise<string>;
+}
+/**
+ * Read a response body as UTF-8, keeping at most `maxBytes`. Streams when the
+ * body is available (cancelling the rest); otherwise falls back to `text()`
+ * after rejecting an oversized declared Content-Length. Returns the (possibly
+ * truncated) text and whether it was truncated.
+ */
+export declare function readTextCapped(res: ReadableResponse, maxBytes?: number): Promise<{
+    text: string;
+    truncated: boolean;
+}>;
+/** Discard a response body without reading it (frees the connection). */
+export declare function discardBody(res: {
+    body?: ReadableStream<Uint8Array> | null;
+}): Promise<void>;
+export interface FetchJsonOptions {
+    timeoutMs: number;
+    headers?: Record<string, string>;
+    maxBytes?: number;
+}
+/**
+ * GET a JSON document with a timeout and size cap. Returns null on any network
+ * error, non-2xx status, oversized body or malformed JSON — callers degrade
+ * gracefully rather than throw.
+ */
+export declare function fetchJson(url: string, opts: FetchJsonOptions): Promise<unknown>;
+/** Narrow an unknown JSON value to a plain object (arrays and null excluded). */
+export declare function asRecord(value: unknown): Record<string, unknown> | null;
+/** A finite number from an unknown JSON value, else null. */
+export declare function finiteNumber(value: unknown): number | null;
+//# sourceMappingURL=http.d.ts.map

package/dist/core/http.js

@@ -0,0 +1,111 @@
+/**
+ * Small, bounded HTTP helpers for NPCs that read untrusted remote content
+ * (weather/geo APIs, GitHub, watched web pages). Every call has a timeout and
+ * every body read has a byte cap, so a slow or hostile server can neither hang
+ * a collection nor balloon memory.
+ */
+/** The `User-Agent` sent by every NPC request. */
+export const NPC_USER_AGENT = 'nocville-npc';
+/** Default cap for a response body read into memory. */
+export const DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
+/** True for an absolute http(s) URL (anything else — file:, data:, javascript: — is refused). */
+export function isHttpUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'http:' || url.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+/** A URL rendered for logs/screens: scheme, host and path only — never credentials or query. */
+export function displayUrl(value) {
+    try {
+        const url = new URL(value);
+        return `${url.protocol}//${url.host}${url.pathname === '/' ? '' : url.pathname}`;
+    }
+    catch {
+        return '(invalid url)';
+    }
+}
+/**
+ * Read a response body as UTF-8, keeping at most `maxBytes`. Streams when the
+ * body is available (cancelling the rest); otherwise falls back to `text()`
+ * after rejecting an oversized declared Content-Length. Returns the (possibly
+ * truncated) text and whether it was truncated.
+ */
+export async function readTextCapped(res, maxBytes = DEFAULT_MAX_BODY_BYTES) {
+    const reader = res.body?.getReader();
+    if (!reader) {
+        const declared = Number(res.headers?.get('content-length') ?? NaN);
+        if (Number.isFinite(declared) && declared > maxBytes)
+            return { text: '', truncated: true };
+        const text = await res.text();
+        return text.length > maxBytes
+            ? { text: text.slice(0, maxBytes), truncated: true }
+            : { text, truncated: false };
+    }
+    const chunks = [];
+    let total = 0;
+    let truncated = false;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (total + value.byteLength > maxBytes) {
+                chunks.push(value.subarray(0, maxBytes - total));
+                total = maxBytes;
+                truncated = true;
+                break;
+            }
+            chunks.push(value);
+            total += value.byteLength;
+        }
+    }
+    finally {
+        if (truncated)
+            await reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+    return { text: new TextDecoder().decode(Buffer.concat(chunks)), truncated };
+}
+/** Discard a response body without reading it (frees the connection). */
+export async function discardBody(res) {
+    await res.body?.cancel().catch(() => undefined);
+}
+/**
+ * GET a JSON document with a timeout and size cap. Returns null on any network
+ * error, non-2xx status, oversized body or malformed JSON — callers degrade
+ * gracefully rather than throw.
+ */
+export async function fetchJson(url, opts) {
+    try {
+        const res = await fetch(url, {
+            signal: AbortSignal.timeout(opts.timeoutMs),
+            headers: { 'User-Agent': NPC_USER_AGENT, Accept: 'application/json', ...opts.headers },
+        });
+        if (!res.ok) {
+            await discardBody(res);
+            return null;
+        }
+        const { text, truncated } = await readTextCapped(res, opts.maxBytes ?? 256 * 1024);
+        if (truncated)
+            return null;
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/** Narrow an unknown JSON value to a plain object (arrays and null excluded). */
+export function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** A finite number from an unknown JSON value, else null. */
+export function finiteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+//# sourceMappingURL=http.js.map

package/dist/core/pixel-art.d.ts

@@ -0,0 +1,38 @@
+import type { ScreenData } from '@nocville/node';
+export interface PixelArtFrames {
+    width: number;
+    height: number;
+    /** RGBA bytes per frame (width × height × 4). */
+    frames: Array<Uint8Array | Uint8ClampedArray>;
+    /** Animation speed when there is more than one frame (1–12, default 4). */
+    fps?: number;
+}
+/** Encode RGBA frames as `pixel-image` screen data. Throws with a fix-it message. */
+export declare function encodePixelArt(art: PixelArtFrames): ScreenData;
+/**
+ * Load a PNG (path or bytes) as pixel-device screen data. For animation, stack frames
+ * top to bottom in one PNG and pass `frameHeight`.
+ */
+export declare function pixelArtFromPng(png: string | Buffer, opts?: {
+    frameHeight?: number;
+    fps?: number;
+}): ScreenData;
+/**
+ * Companion declaration for a pixel device: `size` in tiles (art is 32px per tile).
+ * Freestanding by default so it sits on the floor next to the NPC's home.
+ */
+export declare function pixelDevice(opts: {
+    w: number;
+    h: number;
+    label?: string;
+    placement?: 'freestanding' | 'adjacent-wall' | 'on-desk';
+}): {
+    screenType: 'pixel-device';
+    size: {
+        w: number;
+        h: number;
+    };
+    placement: 'freestanding' | 'adjacent-wall' | 'on-desk';
+    label?: string;
+};
+//# sourceMappingURL=pixel-art.d.ts.map

package/dist/core/pixel-art.js

@@ -0,0 +1,105 @@
+import { readFileSync } from 'node:fs';
+import { PNG } from 'pngjs';
+/**
+ * Helpers for custom pixel-art companions (`screenType: 'pixel-device'`): your NPC's own
+ * device, sign or machine, drawn frameless beside it in the office.
+ *
+ * Art is 32 pixels per tile (a 2×3-tile device is 64×96, like the office furniture) and is
+ * sent as `pixel-image` screen data: a palette of up to 255 colours plus one byte per pixel.
+ * Fully transparent pixels (alpha < 128) become see-through, and several frames stacked top
+ * to bottom animate at `fps`. Push a new image whenever its state changes (e.g. an LED turns
+ * red); the server rate-limits pushes, so animate with frames rather than many pushes.
+ */
+/** Largest single screen-data value the API accepts (base64 pixels). */
+const MAX_VALUE = 220_000;
+const MAX_COLORS = 255;
+const MAX_FRAMES = 16;
+/** Encode RGBA frames as `pixel-image` screen data. Throws with a fix-it message. */
+export function encodePixelArt(art) {
+    const { width, height, frames } = art;
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1)
+        throw new Error('Pixel art needs a positive whole-number width and height.');
+    if (width > 192 || height > 192)
+        throw new Error(`Pixel art is ${width}×${height}; keep it within 192×192 (6×6 tiles).`);
+    if (frames.length < 1 || frames.length > MAX_FRAMES)
+        throw new Error(`Pixel art needs 1–${MAX_FRAMES} frames (got ${frames.length}).`);
+    const size = width * height;
+    for (const frame of frames)
+        if (frame.length !== size * 4)
+            throw new Error(`Each frame must be ${width}×${height} RGBA (${size * 4} bytes).`);
+    // Index 0 is reserved for transparency when any pixel is see-through.
+    const transparent = frames.some((f) => {
+        for (let i = 3; i < f.length; i += 4)
+            if (f[i] < 128)
+                return true;
+        return false;
+    });
+    const colors = new Map();
+    const palette = transparent ? [0, 0, 0] : [];
+    const pixels = Buffer.alloc(size * frames.length);
+    frames.forEach((frame, f) => {
+        for (let i = 0; i < size; i++) {
+            const r = frame[i * 4], g = frame[i * 4 + 1], b = frame[i * 4 + 2];
+            if (transparent && frame[i * 4 + 3] < 128) {
+                pixels[f * size + i] = 0;
+                continue;
+            }
+            const key = (r << 16) | (g << 8) | b;
+            let index = colors.get(key);
+            if (index === undefined) {
+                index = palette.length / 3;
+                if (index > MAX_COLORS)
+                    throw new Error(`Pixel art uses more than ${MAX_COLORS} colours; reduce the palette (pixel art usually needs 8–32).`);
+                colors.set(key, index);
+                palette.push(r, g, b);
+            }
+            pixels[f * size + i] = index;
+        }
+    });
+    const tokens = [`idx8`, `${width}x${height}`, `p${palette.length / 3}`];
+    if (transparent)
+        tokens.push('t0');
+    if (frames.length > 1) {
+        const fps = Math.min(12, Math.max(1, Math.round(art.fps ?? 4)));
+        tokens.push(`f${frames.length}`, `fps${fps}`);
+    }
+    const encoded = pixels.toString('base64');
+    if (encoded.length > MAX_VALUE)
+        throw new Error('Pixel art is too large to send; use fewer frames or a smaller size.');
+    return {
+        layout: 'pixel-image',
+        values: [
+            { label: 'fmt', value: tokens.join(';') },
+            { label: 'palette', value: Buffer.from(palette).toString('base64') },
+            { label: 'pixels', value: encoded },
+        ],
+    };
+}
+/**
+ * Load a PNG (path or bytes) as pixel-device screen data. For animation, stack frames
+ * top to bottom in one PNG and pass `frameHeight`.
+ */
+export function pixelArtFromPng(png, opts = {}) {
+    const image = PNG.sync.read(typeof png === 'string' ? readFileSync(png) : png);
+    const frameHeight = opts.frameHeight ?? image.height;
+    if (frameHeight < 1 || image.height % frameHeight !== 0)
+        throw new Error(`PNG height ${image.height} is not a whole number of ${frameHeight}px frames.`);
+    const frameBytes = image.width * frameHeight * 4;
+    const frames = [];
+    for (let offset = 0; offset < image.data.length; offset += frameBytes)
+        frames.push(image.data.subarray(offset, offset + frameBytes));
+    return encodePixelArt({ width: image.width, height: frameHeight, frames, fps: opts.fps });
+}
+/**
+ * Companion declaration for a pixel device: `size` in tiles (art is 32px per tile).
+ * Freestanding by default so it sits on the floor next to the NPC's home.
+ */
+export function pixelDevice(opts) {
+    return {
+        screenType: 'pixel-device',
+        size: { w: opts.w, h: opts.h },
+        placement: opts.placement ?? 'freestanding',
+        ...(opts.label ? { label: opts.label } : {}),
+    };
+}
+//# sourceMappingURL=pixel-art.js.map

package/dist/core/polling-npc.d.ts

@@ -3,9 +3,21 @@ import type { NpcConfig, CollectedMetrics } from './types.js';
 export interface PollingNpcConfig extends NpcConfig {
     pollInterval?: number;
 }
+/**
+ * Lower bound for any poll interval, so a typo can't exhaust the API's
+ * per-service rate limit (60 pushes/min) or hammer the watched source.
+ */
+export declare const MIN_POLL_INTERVAL_MS = 5000;
 export declare abstract class PollingNPC extends BaseNPC {
     private timer;
-    private collecting;
+    private keepaliveTimer;
+    /** The running collection + push, if any (awaited by `onStop`). */
+    private inflight;
+    /** A `collectNow()` arrived while a collection was in flight: run once more after it. */
+    private rerunRequested;
+    /** The last successfully pushed cycle, replayed (without its screen) by the keepalive. */
+    private lastPushed;
+    private lastPushAt;
     protected pollInterval: number;
     constructor(config: PollingNpcConfig);
     /** Scale staleness to the poll cadence: the server marks unknown at ~2x the interval. */
@@ -13,6 +25,15 @@ export declare abstract class PollingNPC extends BaseNPC {
     protected abstract collect(): Promise<CollectedMetrics>;
     protected onStart(): Promise<void>;
     protected onStop(): Promise<void>;
+    /**
+     * Collect and push now instead of waiting for the next tick — for NPCs that
+     * also react to events (e.g. a fresh error line). Coalesces: if a collection
+     * is already running, exactly one more runs after it.
+     */
+    protected collectNow(): void;
     private runCollection;
+    private collectAndPush;
+    /** Replay the last cycle (minus its screen, which the server keeps) if nothing was pushed recently. */
+    private keepalive;
 }
 //# sourceMappingURL=polling-npc.d.ts.map