flet-box 1.0.6 → 1.0.7

package/bin/utils/imageTools.js

@@ -0,0 +1,271 @@
+/**
+ * @file bin/utils/imageTools.js
+ * @description Finds the lossy image encoder this machine already has, and names
+ * the one command that installs it when it does not.
+ *
+ * `to-png` is the zero-dependency half of image work: it rewrites flat art as the
+ * smallest lossless PNG Node core can encode. A photograph is never small in a
+ * lossless format, and the only honest way to shrink one is a real encoder —
+ * WebP or AVIF. This module does not implement one; it delegates to the platform
+ * binary, exactly as `runCloudflare.js` delegates the tunnel to `cloudflared` and
+ * `buildAndroid.js` delegates compiling to the Android SDK.
+ *
+ * A binary is not an npm dependency, so this stays inside the package contract:
+ * `dependencies: {}`, and nothing here may import outside `node:*`
+ * (scripts/check-cli-install.mjs is the tripwire).
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+/**
+ * One encoder invocation spelled out, so the command that runs it stays generic.
+ *
+ * @typedef {object} Encoder
+ * @property {string} bin       Executable to probe and run.
+ * @property {string} format    Output container it writes.
+ * @property {string} probe     Args that only print a version.
+ * @property {(o: {width: number, quality: number, method: number, src: string, out: string}) => string[]} args
+ */
+
+/** WebP via libwebp's own CLI: the smallest, most predictable surface. */
+const CWEBP = {
+  bin: "cwebp",
+  format: "webp",
+  probe: ["-version"],
+  args: ({ width, quality, method, src, out }) => [
+    "-quiet",
+    "-resize",
+    String(width),
+    "0",
+    "-q",
+    String(quality),
+    "-m",
+    String(method),
+    src,
+    "-o",
+    out,
+  ],
+};
+
+/** ImageMagick, v7 (`magick`) and v6 (`convert`) take the same arguments here. */
+const imagemagick = (bin) => ({
+  bin,
+  format: "webp",
+  probe: ["-version"],
+  args: ({ width, quality, method, src, out }) => [
+    src,
+    "-resize",
+    `${width}x`,
+    "-quality",
+    String(quality),
+    "-define",
+    `webp:method=${method}`,
+    out,
+  ],
+});
+
+/**
+ * Order matters: `cwebp` is the reference encoder for the container, and the two
+ * ImageMagick spellings catch the machines where the distro shipped that instead.
+ */
+const ENCODERS = [CWEBP, imagemagick("magick"), imagemagick("convert")];
+
+/**
+ * The package manager this machine is expected to have.
+ *
+ * macOS and Windows are read off `process.platform`. Linux needs the actual
+ * distribution: `apt`, `dnf` and `pacman` are different sentences for the same
+ * package, and guessing from the kernel would tell an Arch user to run apt.
+ *
+ * @returns {{id: string, name: string, install: string[]}}
+ */
+export const platformInstaller = () => {
+  if (process.platform === "darwin") {
+    return { id: "brew", name: "Homebrew", install: ["brew", "install", "webp"] };
+  }
+  if (process.platform === "win32") {
+    return {
+      id: "winget",
+      name: "winget",
+      install: ["winget", "install", "--id", "Google.WebP", "-e", "--accept-package-agreements", "--accept-source-agreements"],
+    };
+  }
+  if (process.platform !== "linux") {
+    return { id: "unknown", name: process.platform, install: [] };
+  }
+  // /etc/os-release is the only ID every mainstream distro keeps current.
+  let lines = [];
+  try {
+    lines = fs.readFileSync("/etc/os-release", "utf8").split("\n");
+  } catch {
+    lines = [];
+  }
+  const read = (key) => {
+    const hit = lines.find((l) => l.startsWith(`${key}=`));
+    return hit ? hit.slice(key.length + 1).replace(/^"|"$/g, "") : "";
+  };
+  const family = [read("ID"), ...read("ID_LIKE").split(/\s+/)].filter(Boolean);
+  if (family.some((f) => /debian|ubuntu|linuxmint/.test(f))) {
+    return { id: "apt", name: "apt", install: ["sudo", "apt-get", "install", "-y", "webp"] };
+  }
+  if (family.some((f) => /fedora|rhel|centos|amzn/.test(f))) {
+    return { id: "dnf", name: "dnf", install: ["sudo", "dnf", "install", "-y", "libwebp-tools"] };
+  }
+  if (family.some((f) => /arch|manjaro|endeavouros/.test(f))) {
+    return { id: "pacman", name: "pacman", install: ["sudo", "pacman", "-S", "--noconfirm", "libwebp"] };
+  }
+  return { id: "apk", name: "apk", install: ["sudo", "apk", "add", "--no-cache", "webp"] };
+};
+
+/**
+ * True when `bin` is runnable — probed with `--version`, never with `which`,
+ * so a shim that exists but is broken is not counted as an encoder.
+ *
+ * @param {string} bin
+ * @returns {boolean}
+ */
+const isRunnable = (bin) => {
+  const probe = spawnSync(bin, ["--version"], { encoding: "utf8" });
+  return !probe.error;
+};
+
+/**
+ * @returns {Encoder|null} The first usable encoder on PATH.
+ */
+export const findEncoder = () => {
+  for (const candidate of ENCODERS) {
+    if (isRunnable(candidate.bin)) return candidate;
+  }
+  return null;
+};
+
+/**
+ * Runs one encoder to a temp file and returns the bytes it produced.
+ *
+ * @param {Encoder} encoder
+ * @param {{src: string, width: number, quality: number, method?: number, out: string}} opts
+ * @returns {number|null} Written size, or null when the encoder failed.
+ */
+export const encode = (encoder, { src, width, quality, method = 6, out }) => {
+  const res = spawnSync(
+    encoder.bin,
+    encoder.args({ src, width, quality, method, out }),
+    { stdio: "ignore", encoding: "utf8" },
+  );
+  if (res.error || res.status !== 0 || !fs.existsSync(out)) return null;
+  return fs.statSync(out).size;
+};
+
+/**
+ * Asks before touching the system. Installing a package is a machine-wide change
+ * with a hundred ways to be wrong (no brew, no sudo rights, a locked-down laptop),
+ * and a build command that silently runs `sudo` is not something a developer
+ * expects from a UI framework's CLI.
+ *
+ * @param {Encoder|null} encoder - What was already found, if anything.
+ * @param {{autoInstall: boolean, isTTY: boolean, quiet: boolean}} opts
+ * @returns {Promise<Encoder|null>} The encoder to use, or null when it is missing.
+ */
+export const ensureEncoder = async (encoder, { autoInstall = false, isTTY = process.stdout.isTTY, quiet = false } = {}) => {
+  if (encoder) return encoder;
+
+  const installer = platformInstaller();
+  const said = (line) => !quiet && console.log(line);
+  const found = findEncoder();
+  if (found) return found;
+
+  console.log("");
+  console.log(`  No lossy WebP encoder is on PATH (tried: ${ENCODERS.map((e) => e.bin).join(", ")}).`);
+  if (!installer.install.length) {
+    said(`  This platform (${process.platform}) has no known package manager here.`);
+    console.log("  Install libwebp's `cwebp` by hand, or keep the lossless `flet-box to-png`.");
+    return null;
+  }
+  const command = installer.install.join(" ");
+  console.log(`  Install it with ${installer.name}:  ${command}`);
+
+  if (!autoInstall) {
+    said("  Re-run with --install and this CLI will do it for you.");
+    return null;
+  }
+  if (!isTTY) {
+    console.log("  --install needs a terminal (it may ask for a password). Run the command above and retry.");
+    return null;
+  }
+  const res = spawnSync(command.split(" ")[0], command.split(" ").slice(1), { stdio: "inherit" });
+  if (res.error || res.status !== 0) {
+    console.log(`  ${command} did not succeed — that machine decides, not this CLI.`);
+    return null;
+  }
+  const after = findEncoder();
+  if (after) console.log(`  Installed: ${after.bin}`);
+  return after;
+};
+
+/**
+ * Where a scratch file can safely sit next to the asset being written.
+ *
+ * @param {string} dir
+ * @param {string} name
+ * @returns {string}
+ */
+export const tempIn = (dir, name) => path.join(dir, `.${name}.fletbox-tmp.webp`);
+
+/**
+ * True when any pixel of a decoded frame is see-through.
+ *
+ * @param {Buffer} rgba
+ * @returns {boolean}
+ */
+export const hasTransparency = (rgba) => {
+  for (let i = 3; i < rgba.length; i += 4) if (rgba[i] !== 255) return true;
+  return false;
+};
+
+/**
+ * True when the WebP bytes carry an alpha plane.
+ *
+ * There is no WebP decoder in this package — that is what `to-png` declines at
+ * `bin/utils/images/index.js` — so "read every pixel back" is not available here.
+ * The container is: a transparent WebP says so in its chunk layout, and a lossy
+ * encoder that dropped the plane produces a file that simply lacks it. Three
+ * spellings, because the encoder chooses between them:
+ *
+ *   VP8X  extended header, bit 4 of its first flag byte is the A flag
+ *   ALPH  the separate alpha chunk a lossy frame with transparency gets
+ *   VP8L  lossless: bit 28 of the packed size/version word says alpha is used
+ *
+ * A plain lossy `VP8 ` frame has no alpha at all, which is the case this catches:
+ * an icon or a sticker flattened onto white would otherwise ship as the picture.
+ *
+ * @param {Buffer} buf - WebP file bytes.
+ * @returns {boolean}
+ */
+export const webpCarriesAlpha = (buf) => {
+  if (buf.length < 12) return false;
+  if (buf.toString("ascii", 0, 4) !== "RIFF") return false;
+  if (buf.toString("ascii", 8, 12) !== "WEBP") return false;
+  let at = 12;
+  while (at + 8 <= buf.length) {
+    const fourcc = buf.toString("ascii", at, at + 4);
+    const size = buf.readUInt32LE(at + 4);
+    const body = buf.subarray(at + 8, Math.min(at + 8 + size, buf.length));
+    if (fourcc === "ALPH") return true;
+    if (fourcc === "VP8X") return body.length > 0 && (body[0] & 0x10) !== 0;
+    if (fourcc === "VP8L") {
+      // byte 0 is the 0x2f lossless signature, then the packed 32-bit field.
+      if (body.length < 5) return false;
+      return ((body.readUInt32LE(1) >> 28) & 1) === 1;
+    }
+    // Chunks are padded to an even byte count.
+    at += 8 + size + (size % 2);
+  }
+  return false;
+};
+
+/** Kept for callers that want to report the machine they probed. */
+export const describeMachine = () => `${os.platform()}/${os.arch()} · ${platformInstaller().name}`;
+

package/bin/utils/images/bmp.js

@@ -0,0 +1,99 @@
+/**
+ * @file bin/utils/images/bmp.js
+ * @description Uncompressed Windows BMP reader.
+ *
+ * BMP is the one raster format whose pixels can be lifted straight out of the
+ * file, so this is mostly header arithmetic. Run-length variants (BI_RLE8,
+ * BI_RLE4) and OS/2 headers are refused rather than guessed at: they are
+ * decades old, rare in an assets folder, and a half-read RLE stream produces
+ * garbage that still looks like a picture.
+ */
+
+import UnsupportedImage from "./unsupported.js";
+
+/**
+ * Decodes a BMP into RGBA.
+ *
+ * @param {Buffer} buf - File bytes.
+ * @returns {{ width: number, height: number, rgba: Buffer }}
+ * @throws {Error} Naming the unsupported combination of header fields.
+ */
+export const decodeBmp = (buf) => {
+  if (buf.length < 54 || buf.toString("ascii", 0, 2) !== "BM") {
+    throw new Error("not a BMP: missing the BM signature");
+  }
+
+  const dataOffset = buf.readUInt32LE(10);
+  const headerSize = buf.readUInt32LE(14);
+  if (headerSize < 40) throw new UnsupportedImage("BMP", "OS/2 BITMAPCOREHEADER is not implemented");
+
+  const width = buf.readInt32LE(18);
+  const rawHeight = buf.readInt32LE(22);
+  const bitCount = buf.readUInt16LE(28);
+  const compression = buf.readUInt32LE(30);
+
+  if (compression !== 0) {
+    throw new UnsupportedImage("BMP", `compression mode ${compression} (only uncompressed BI_RGB is implemented)`);
+  }
+  if (![1, 4, 8, 24, 32].includes(bitCount)) {
+    throw new UnsupportedImage("BMP", `${bitCount}-bit depth is not implemented (1, 4, 8, 24 and 32 are)`);
+  }
+
+  const topDown = rawHeight < 0;
+  const height = Math.abs(rawHeight);
+  const palette = [];
+  if (bitCount <= 8) {
+    // `biClrUsed` lives at 46 — reading it earlier returns the low bytes of the
+    // image size, and a file whose "palette" claims 67 million entries is only
+    // one bad offset away from exhausting the heap.
+    const paletteStart = 14 + headerSize;
+    const declared = buf.readUInt32LE(46);
+    const needed = 1 << bitCount;
+    const entries = declared > 0 ? Math.min(declared, needed) : needed;
+    const room = Math.floor((dataOffset - paletteStart) / 4);
+    if (room < entries) {
+      throw new Error(`BMP palette claims ${entries} entries but only ${Math.max(0, room)} fit before the pixels`);
+    }
+    for (let i = 0; i < entries; i++) {
+      const base = paletteStart + i * 4;
+      palette.push([buf[base + 2], buf[base + 1], buf[base], 255]);
+    }
+  }
+
+  const rgba = Buffer.alloc(width * height * 4);
+  const rowBytes = Math.ceil((width * bitCount) / 8);
+  const stride = Math.ceil(rowBytes / 4) * 4;
+
+  for (let y = 0; y < height; y++) {
+    const sourceRow = dataOffset + (topDown ? y : height - 1 - y) * stride;
+    for (let x = 0; x < width; x++) {
+      const dst = (y * width + x) * 4;
+      if (bitCount === 32) {
+        const base = sourceRow + x * 4;
+        rgba[dst] = buf[base + 2];
+        rgba[dst + 1] = buf[base + 1];
+        rgba[dst + 2] = buf[base];
+        rgba[dst + 3] = buf[base + 3];
+      } else if (bitCount === 24) {
+        const base = sourceRow + x * 3;
+        rgba[dst] = buf[base + 2];
+        rgba[dst + 1] = buf[base + 1];
+        rgba[dst + 2] = buf[base];
+        rgba[dst + 3] = 255;
+      } else {
+        const shift = bitCount === 1 ? 7 - (x % 8) : bitCount === 4 ? (x % 2 ? 0 : 4) : 0;
+        const mask = (1 << bitCount) - 1;
+        const index = (buf[sourceRow + Math.floor((x * bitCount) / 8)] >> shift) & mask;
+        const colour = palette[index] || [0, 0, 0, 255];
+        rgba[dst] = colour[0];
+        rgba[dst + 1] = colour[1];
+        rgba[dst + 2] = colour[2];
+        rgba[dst + 3] = colour[3];
+      }
+    }
+  }
+
+  return { width, height, rgba };
+};
+
+export default decodeBmp;

package/bin/utils/images/gif.js

@@ -0,0 +1,244 @@
+/**
+ * @file bin/utils/images/gif.js
+ * @description GIF reader: LZW, global or local palettes, transparency, interlace.
+ *
+ * A GIF is a canvas with one or more frames on it, and a PNG is one still
+ * image, so the conversion has to pick a frame. This takes the first one and
+ * places it at its own offset inside the logical screen, which is where a
+ * browser would show it. An animated file is converted with a note saying only
+ * the first frame survived — silently dropping the rest of a cartoon would be
+ * the worse half of that trade.
+ */
+
+/**
+ * Decodes a GIF into RGBA.
+ *
+ * @param {Buffer} buf - File bytes.
+ * @returns {{ width: number, height: number, rgba: Buffer, note?: string }}
+ * @throws {Error} Naming the corruption or the feature this reader lacks.
+ */
+export const decodeGif = (buf) => {
+  const magic = buf.toString("ascii", 0, 6);
+  if (magic !== "GIF87a" && magic !== "GIF89a") throw new Error("not a GIF: bad signature");
+
+  const canvasWidth = buf.readUInt16LE(6);
+  const canvasHeight = buf.readUInt16LE(8);
+  const packed = buf[10];
+  let offset = 13;
+
+  let globalTable = null;
+  if (packed & 0x80) {
+    globalTable = readColorTable(buf, offset, 2 << (packed & 7));
+    offset += 3 * (2 << (packed & 7));
+  }
+
+  let transparentIndex = -1;
+  let frames = 0;
+  let width = canvasWidth;
+  let height = canvasHeight;
+  let rgba = null;
+
+  while (offset < buf.length) {
+    const introducer = buf[offset];
+    offset++;
+
+    if (introducer === 0x3b) break; // trailer
+
+    if (introducer === 0x21) {
+      const label = buf[offset];
+      const blocks = readBlocks(buf, offset + 1);
+      if (label === 0xf9 && blocks.data.length >= 4 && blocks.data[0] & 0x01) {
+        transparentIndex = blocks.data[3];
+      }
+      offset = blocks.next;
+      continue;
+    }
+
+    if (introducer !== 0x2c) throw new Error(`unexpected GIF block 0x${introducer.toString(16)}`);
+
+    const x = buf.readUInt16LE(offset);
+    const y = buf.readUInt16LE(offset + 2);
+    const frameWidth = buf.readUInt16LE(offset + 4);
+    const frameHeight = buf.readUInt16LE(offset + 6);
+    const framePacked = buf.readUInt16LE(offset + 8) & 0xff;
+    offset += 9;
+
+    let table = globalTable;
+    if (framePacked & 0x80) {
+      const entries = 2 << (framePacked & 7);
+      table = readColorTable(buf, offset, entries);
+      offset += 3 * entries;
+    }
+    if (!table) throw new Error("GIF frame has no colour table");
+
+    frames++;
+    if (frames === 1) {
+      width = canvasWidth;
+      height = canvasHeight;
+      rgba = Buffer.alloc(canvasWidth * canvasHeight * 4);
+      const interlaced = (framePacked & 0x40) !== 0;
+      const pixels = decodeLzw(buf, offset, frameWidth * frameHeight);
+      const rows = interlaced ? deinterlace(frameHeight) : Array.from({ length: frameHeight }, (_, i) => i);
+
+      for (let row = 0; row < frameHeight; row++) {
+        const targetY = y + rows[row];
+        if (targetY < 0 || targetY >= canvasHeight) continue;
+        for (let col = 0; col < frameWidth; col++) {
+          const targetX = x + col;
+          if (targetX < 0 || targetX >= canvasWidth) continue;
+          const index = pixels[row * frameWidth + col];
+          const colour = table[index] || [0, 0, 0, 255];
+          const dst = (targetY * canvasWidth + targetX) * 4;
+          rgba[dst] = colour[0];
+          rgba[dst + 1] = colour[1];
+          rgba[dst + 2] = colour[2];
+          rgba[dst + 3] = index === transparentIndex ? 0 : colour[3];
+        }
+      }
+    }
+    offset = skipImage(buf, offset);
+  }
+
+  if (!rgba) throw new Error("GIF has no image block");
+
+  return {
+    width,
+    height,
+    rgba,
+    note: frames > 1 ? `${frames} frames: only the first was kept` : undefined,
+  };
+};
+
+/**
+ * @param {Buffer} buf
+ * @param {number} start - Offset of the first table entry.
+ * @param {number} entries
+ * @returns {number[][]} `[r, g, b, a]` per entry; GIF stores no alpha.
+ */
+const readColorTable = (buf, start, entries) => {
+  const table = [];
+  for (let i = 0; i < entries; i++) {
+    const base = start + i * 3;
+    table.push([buf[base], buf[base + 1], buf[base + 2], 255]);
+  }
+  return table;
+};
+
+/**
+ * Walks a GIF sub-block chain.
+ *
+ * @param {Buffer} buf
+ * @param {number} start - Offset of the first size byte.
+ * @returns {{ data: Buffer, next: number }}
+ */
+const readBlocks = (buf, start) => {
+  const parts = [];
+  let offset = start;
+  while (offset < buf.length) {
+    const size = buf[offset];
+    offset++;
+    if (size === 0) break;
+    parts.push(buf.subarray(offset, offset + size));
+    offset += size;
+  }
+  return { data: Buffer.concat(parts), next: offset };
+};
+
+/**
+ * Reads an image's LZW sub-blocks and decodes them into palette indices.
+ *
+ * @param {Buffer} buf
+ * @param {number} offset - Where the LZW minimum code size byte sits.
+ * @param {number} count - Pixels in this frame.
+ * @returns {Uint8Array}
+ */
+const decodeLzw = (buf, offset, count) => {
+  const { data } = readBlocks(buf, offset + 1);
+  const minCodeSize = buf[offset];
+  const clearCode = 1 << minCodeSize;
+  const endCode = clearCode + 1;
+
+  const pixels = new Uint8Array(count);
+  let dict = [];
+  let codeSize = minCodeSize + 1;
+  let next = endCode + 1;
+  let bitPos = 0;
+  let written = 0;
+  let previous = null;
+
+  const resetDict = () => {
+    dict = [];
+    for (let i = 0; i < clearCode; i++) dict[i] = [i];
+    dict[clearCode] = [];
+    dict[endCode] = [];
+    codeSize = minCodeSize + 1;
+    next = endCode + 1;
+    previous = null;
+  };
+
+  const readCode = () => {
+    let code = 0;
+    for (let i = 0; i < codeSize; i++) {
+      const byteIndex = (bitPos + i) >> 3;
+      if (byteIndex >= data.length) return -1;
+      code |= ((data[byteIndex] >> ((bitPos + i) & 7)) & 1) << i;
+    }
+    bitPos += codeSize;
+    return code;
+  };
+
+  resetDict();
+  while (written < count) {
+    const code = readCode();
+    if (code === -1 || code === endCode) break;
+    if (code === clearCode) {
+      resetDict();
+      continue;
+    }
+
+    let entry = dict[code];
+    if (!entry) {
+      // The classic KwKwK case: the code being asked for is the one this
+      // iteration is about to define, so the new entry is `previous` plus its
+      // own first index.
+      if (!previous) throw new Error("GIF LZW stream references an undefined code");
+      entry = [...previous, previous[0]];
+      dict[next++] = entry;
+    } else if (previous) {
+      dict[next++] = [...previous, entry[0]];
+    }
+    previous = entry;
+
+    for (const value of entry) {
+      if (written < count) pixels[written++] = value;
+    }
+    if (next === (1 << codeSize) && codeSize < 12) codeSize++;
+  }
+
+  return pixels;
+};
+
+/**
+ * Row order of an interlaced GIF: 4/8, then 2/8, then 1/4, then 1/2 passes.
+ *
+ * @param {number} height
+ * @returns {number[]} Destination row for each stored row, in order.
+ */
+const deinterlace = (height) => {
+  const rows = [];
+  for (let pass = 0; pass < 4; pass++) {
+    const start = [0, 4, 2, 1][pass];
+    const step = [8, 8, 4, 2][pass];
+    for (let y = start; y < height; y += step) rows.push(y);
+  }
+  return rows;
+};
+
+/**
+ * @param {Buffer} buf
+ * @param {number} offset - Where the LZW minimum code size byte sits.
+ * @returns {number} Offset after this image's sub-blocks.
+ */
+const skipImage = (buf, offset) => readBlocks(buf, offset + 1).next;
+
+export default decodeGif;