@nocville/npc 0.2.2 → 0.2.3

package/README.md

@@ -150,16 +150,34 @@ on your map automatically and despawns when you press Ctrl-C. Once you've run
 | `github-watcher`        | New commits on a commit board                      | `nocville-npc github-watcher --repo=owner/name`        |
 | `web-page-watcher`      | A web page rendered as a pixel-art TV              | `nocville-npc web-page-watcher --url=https://…`        |
 
-Run `nocville-npc --help` to see every flag. A few notes:
-
+Run `nocville-npc --help` to see every flag. Poll intervals below 5 seconds are raised to 5
+seconds. A few notes:
+
+- **system-monitor**: `--disk-path=/data` picks the volume; thresholds are percentages
+  (`--cpu-warn`/`--cpu-crit`, `--mem-…`, `--disk-…`). On macOS, memory counts the file cache as
+  available, like Activity Monitor.
+- **internet-connectivity**: `--dns-hosts`, `--http-urls` (http/https only) and
+  `--latency-hosts` take comma-separated lists; latency targets accept `host:port` or
+  `[ipv6]:port`. `--timeout=<ms>` bounds each check (default 5000).
+- **process-watcher**: matches executable names, so `--processes=python` also finds `python3.11`
+  but `sh` does not match `bash`. Use a full path to match one binary exactly. macOS and Linux
+  only.
 - **log-watcher**: `--error-pattern="ERROR|FATAL" --window=300 --error-warn=5 --error-crit=20`.
+  Files are followed across log rotation and may be created after the watcher starts. Lines
+  shown in the office have anything that looks like a secret (tokens, passwords, keys, URL
+  credentials) redacted, but treat the screen as visible to your whole team.
 - **receptionist**: weather comes from the keyless open-meteo API. Set the place with
-  `--lat=52.5 --lon=13.4` or `--location=…` (otherwise it uses IP geolocation). Add
+  `--lat=52.5 --lon=13.4` or `--location=…`. Without either, it estimates your location from
+  your public IP via ipapi.co; pass `--no-ip-geo` to turn that off and show only the time. Add
   `--fahrenheit` for °F.
-- **github-watcher**: uses ETag polling. Pass `--token=$GITHUB_TOKEN` for a higher rate limit.
+- **github-watcher**: uses ETag polling. Set `GITHUB_TOKEN` for private repos and a higher rate
+  limit (`--token` also works, but flags are visible to other users in the process list).
+  Without a token it polls every 90 seconds to stay within GitHub's 60 requests per hour.
 - **web-page-watcher**: the pixel-art TV needs `npm i puppeteer-core` and a local
   Chrome/Chromium (`--chrome-path` or `CHROME_PATH`). Without them it falls back to a
-  title/status ticker. Other options: `--mode=auto|screenshot|basic` and `--screen=160x120`.
+  title/status ticker. Other options: `--mode=auto|screenshot|basic` and `--screen=160x120`
+  (up to 320x240). Only `http(s)` URLs are accepted. Chrome runs with its sandbox unless you're
+  root or pass `--no-chrome-sandbox`; only disable it for pages you trust.
 
 ## Programmatic use
 

package/dist/cjs/cli.js

@@ -38,6 +38,7 @@ const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const config_js_1 = require("./core/config.js");
+const errors_js_1 = require("./core/errors.js");
 const logger_js_1 = require("./core/logger.js");
 const session_filter_js_1 = require("./core/session-filter.js");
 // NPC modules are imported lazily per command: `claude-code hook` / `codex hook`
@@ -112,17 +113,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)
@@ -133,23 +140,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() {
@@ -310,18 +324,10 @@ async function main() {
             if (!config.serviceId) {
                 config.serviceId = 'internet-connectivity';
             }
-            const dnsHosts = (0, config_js_1.stringFlag)(parsed.flags, 'dns-hosts')?.split(',');
-            const httpUrls = (0, config_js_1.stringFlag)(parsed.flags, 'http-urls')?.split(',');
-            const latencyHostsRaw = (0, config_js_1.stringFlag)(parsed.flags, 'latency-hosts')?.split(',');
-            const latencyHosts = latencyHostsRaw?.map((h) => ({ host: h.trim(), port: 80 }));
             const { InternetConnectivityNPC } = await Promise.resolve().then(() => __importStar(require('./npcs/internet-connectivity/index.js')));
             const npc = new InternetConnectivityNPC({
                 ...config,
-                pollInterval: (0, config_js_1.numberFlag)(parsed.flags, 'poll-interval'),
-                dnsHosts,
-                httpUrls,
-                latencyHosts,
-                slowThreshold: (0, config_js_1.numberFlag)(parsed.flags, 'slow-threshold'),
+                ...InternetConnectivityNPC.configFromFlags(parsed.flags),
             });
             logger.info('Starting internet-connectivity NPC');
             await npc.start();
@@ -331,8 +337,8 @@ async function main() {
             if (!config.serviceId) {
                 config.serviceId = 'process-watcher';
             }
-            const processesStr = (0, config_js_1.stringFlag)(parsed.flags, 'processes');
-            if (!processesStr) {
+            const processes = (0, config_js_1.listFlag)(parsed.flags, 'processes');
+            if (!processes) {
                 console.error('Error: --processes is required (comma-separated list)');
                 process.exit(1);
             }
@@ -340,7 +346,7 @@ async function main() {
             const npc = new ProcessWatcherNPC({
                 ...config,
                 pollInterval: (0, config_js_1.numberFlag)(parsed.flags, 'poll-interval'),
-                processes: processesStr.split(','),
+                processes,
                 cpuWarn: (0, config_js_1.numberFlag)(parsed.flags, 'cpu-warn'),
                 memWarn: (0, config_js_1.numberFlag)(parsed.flags, 'mem-warn'),
             });
@@ -349,8 +355,8 @@ async function main() {
             break;
         }
         case 'log-watcher': {
-            const filesStr = (0, config_js_1.stringFlag)(parsed.flags, 'files');
-            if (!filesStr) {
+            const files = (0, config_js_1.listFlag)(parsed.flags, 'files');
+            if (!files) {
                 console.error('Error: --files is required (comma-separated list)');
                 process.exit(1);
             }
@@ -360,7 +366,7 @@ async function main() {
             const { LogWatcherNPC } = await Promise.resolve().then(() => __importStar(require('./npcs/log-watcher/index.js')));
             const npc = new LogWatcherNPC({
                 ...config,
-                files: filesStr.split(','),
+                files,
                 errorPattern: (0, config_js_1.stringFlag)(parsed.flags, 'error-pattern'),
                 warningPattern: (0, config_js_1.stringFlag)(parsed.flags, 'warning-pattern'),
                 windowSeconds: (0, config_js_1.numberFlag)(parsed.flags, 'window'),
@@ -384,6 +390,7 @@ async function main() {
                 lon: (0, config_js_1.numberFlag)(parsed.flags, 'lon'),
                 location: (0, config_js_1.stringFlag)(parsed.flags, 'location'),
                 fahrenheit: (0, config_js_1.boolFlag)(parsed.flags, 'fahrenheit') ?? false,
+                ipGeo: (0, config_js_1.boolFlag)(parsed.flags, 'no-ip-geo') !== true,
             });
             logger.info('Starting receptionist NPC');
             await npc.start();
@@ -400,11 +407,15 @@ async function main() {
                 config.serviceId = `github-${shortName.replace(/[^a-zA-Z0-9_-]/g, '-')}`.slice(0, 100);
             }
             const { GitHubWatcherNPC } = await Promise.resolve().then(() => __importStar(require('./npcs/github-watcher/index.js')));
+            const tokenFlag = (0, config_js_1.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: (0, config_js_1.stringFlag)(parsed.flags, 'branch'),
-                token: (0, config_js_1.stringFlag)(parsed.flags, 'token') ?? process.env['GITHUB_TOKEN'],
+                token: tokenFlag ?? process.env['GITHUB_TOKEN'],
                 pollInterval: (0, config_js_1.numberFlag)(parsed.flags, 'poll-interval'),
             });
             logger.info('Starting github-watcher NPC');
@@ -420,22 +431,28 @@ async function main() {
             const { hostnameOf } = await Promise.resolve().then(() => __importStar(require('./npcs/web-page-watcher/basic-mode.js')));
             const { parseDimensions } = await Promise.resolve().then(() => __importStar(require('./npcs/web-page-watcher/defaults.js')));
             const { WebPageWatcherNPC } = await Promise.resolve().then(() => __importStar(require('./npcs/web-page-watcher/index.js')));
-            const parseWxH = (v) => v ? (parseDimensions(v) ?? undefined) : undefined;
+            const parseWxH = (flag) => {
+                const v = (0, config_js_1.stringFlag)(parsed.flags, flag);
+                if (v === undefined)
+                    return undefined;
+                const dims = parseDimensions(v);
+                if (!dims)
+                    throw new errors_js_1.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 = (0, config_js_1.stringFlag)(parsed.flags, 'mode');
-            const mode = modeFlag === 'auto' || modeFlag === 'screenshot' || modeFlag === 'basic'
-                ? modeFlag
-                : undefined;
-            const viewport = parseWxH((0, config_js_1.stringFlag)(parsed.flags, 'viewport'));
-            const screen = parseWxH((0, config_js_1.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: (0, config_js_1.stringFlag)(parsed.flags, 'mode'),
+                chromeSandbox: (0, config_js_1.boolFlag)(parsed.flags, 'no-chrome-sandbox') !== true,
                 chromePath: (0, config_js_1.stringFlag)(parsed.flags, 'chrome-path'),
                 waitUntil: (0, config_js_1.stringFlag)(parsed.flags, 'wait-until'),
                 viewportWidth: viewport?.width,
@@ -578,6 +595,10 @@ main().catch((err) => {
         process.stdout.write('{}\n');
         return;
     }
+    if (err instanceof errors_js_1.NpcConfigError) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
     console.error('Fatal error:', err);
     process.exit(1);
 });

package/dist/cjs/core/base-npc.js

@@ -42,6 +42,13 @@ class BaseNPC {
         const name = this.displayName;
         return name ? (0, text_js_1.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';
@@ -116,6 +123,7 @@ class BaseNPC {
             message: metrics.message ? (0, text_js_1.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/cjs/core/config.js

@@ -4,6 +4,7 @@ exports.parseArgs = parseArgs;
 exports.resolveConfig = resolveConfig;
 exports.stringFlag = stringFlag;
 exports.boolFlag = boolFlag;
+exports.listFlag = listFlag;
 exports.numberFlag = numberFlag;
 const user_config_js_1 = require("./user-config.js");
 /**
@@ -96,11 +97,27 @@ 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.
+ */
+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;
+}
 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/cjs/core/errors.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NpcConfigError = void 0;
+exports.assertPosix = assertPosix;
+/**
+ * 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.
+ */
+class NpcConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NpcConfigError';
+    }
+}
+exports.NpcConfigError = NpcConfigError;
+/** Throw an NpcConfigError on Windows, for NPCs that rely on POSIX tools or paths. */
+function assertPosix(npcName, hint) {
+    if (process.platform === 'win32') {
+        throw new NpcConfigError(`${npcName} is not supported on Windows. ${hint}`);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/cjs/core/http.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_BODY_BYTES = exports.NPC_USER_AGENT = void 0;
+exports.isHttpUrl = isHttpUrl;
+exports.displayUrl = displayUrl;
+exports.readTextCapped = readTextCapped;
+exports.discardBody = discardBody;
+exports.fetchJson = fetchJson;
+exports.asRecord = asRecord;
+exports.finiteNumber = finiteNumber;
+/** The `User-Agent` sent by every NPC request. */
+exports.NPC_USER_AGENT = 'nocville-npc';
+/** Default cap for a response body read into memory. */
+exports.DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
+/** True for an absolute http(s) URL (anything else — file:, data:, javascript: — is refused). */
+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. */
+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.
+ */
+async function readTextCapped(res, maxBytes = exports.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). */
+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.
+ */
+async function fetchJson(url, opts) {
+    try {
+        const res = await fetch(url, {
+            signal: AbortSignal.timeout(opts.timeoutMs),
+            headers: { 'User-Agent': exports.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). */
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** A finite number from an unknown JSON value, else null. */
+function finiteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+//# sourceMappingURL=http.js.map

package/dist/cjs/core/pixel-art.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodePixelArt = encodePixelArt;
+exports.pixelArtFromPng = pixelArtFromPng;
+exports.pixelDevice = pixelDevice;
+const node_fs_1 = require("node:fs");
+const pngjs_1 = require("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. */
+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`.
+ */
+function pixelArtFromPng(png, opts = {}) {
+    const image = pngjs_1.PNG.sync.read(typeof png === 'string' ? (0, node_fs_1.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.
+ */
+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