slidemind 0.1.8 → 0.2.0

package/src/bridge/engine-download.mjs

@@ -9,8 +9,16 @@
 import fs from "node:fs";
 import path from "node:path";
 
+import {
+  DIMENSION_PROBE_BYTES,
+  imageSizeFromBuffer,
+  svgSizeFromMarkup,
+} from "./image-dimensions.mjs";
 import { describeRecolor } from "./recolor.mjs";
 
+// Every image format an engine accepts, plus the alias spellings seen in the
+// wild. Mirrors the add-in's `searchImage` set (lib/image-formats.ts there);
+// `extFromMime`'s `image/*` fallback below still covers anything newer.
 const MIME_EXT = {
   "image/svg+xml": "svg",
   "image/png": "png",
@@ -18,6 +26,9 @@ const MIME_EXT = {
   "image/jpg": "jpg",
   "image/webp": "webp",
   "image/gif": "gif",
+  "image/bmp": "bmp",
+  "image/x-ms-bmp": "bmp",
+  "image/tiff": "tiff",
 };
 
 // Derive a usable file extension from an engine result's MIME type. The brand
@@ -42,8 +53,186 @@ export function extFromMime(mimeType) {
   return "bin";
 }
 
+// Below this, a transfer finishes faster than a progress line is worth reading.
+// Most brand icons and slide slices are well under it, so the common case stays
+// silent.
+const PROGRESS_MIN_BYTES = 2 * 1024 * 1024;
+/** Emit at most one line per this much progress. */
+const PROGRESS_STEP_BYTES = 4 * 1024 * 1024;
+
+const mb = (n) => (n / (1024 * 1024)).toFixed(1);
+
+// Progress reporter for a streamed transfer.
+//
+// Deliberately NOT an in-place bar: this CLI's convention (see
+// `renderProgressPrinter` in bin/slidemind.mjs — "one stderr line per state
+// change — works in plain logs and TTYs alike") is milestone lines, because the
+// primary consumer is an agent reading piped stdout, where `\r` repainting is
+// noise rather than motion. So: nothing for small files, and a line every few MB
+// for large ones, on stderr so it never pollutes parseable stdout.
+export function createTransferProgress(label, write = process.stderr.write.bind(process.stderr)) {
+  let nextAt = PROGRESS_STEP_BYTES;
+  let announced = false;
+  return (bytesWritten, total) => {
+    if (total != null && total < PROGRESS_MIN_BYTES) return;
+    if (bytesWritten < nextAt) return;
+    nextAt = bytesWritten + PROGRESS_STEP_BYTES;
+    if (total != null && total > 0) {
+      const pct = Math.min(99, Math.floor((bytesWritten / total) * 100));
+      write(`  ${label}: ${mb(bytesWritten)}/${mb(total)} MB (${pct}%)…\n`);
+    } else {
+      // No content-length (a decoded/chunked stream): report absolute progress.
+      write(`  ${label}: ${mb(bytesWritten)} MB…\n`);
+    }
+    announced = true;
+    return announced;
+  };
+}
+
+const ascii = (s) => [...s].map((c) => c.charCodeAt(0));
+
+// Magic-number signatures for the image formats an engine ACCEPTS — the add-in's
+// `searchImage` set (lib/image-formats.ts there, EngineFileExtensions.search_image
+// in its API). An engine cannot hold a format it refuses at ingest, so this list
+// is complete by construction; keep it in step with that set.
+//
+// `svg` is absent deliberately: it is XML with no signature, so it can only be
+// trusted from its declared type.
+const MAGIC_SIGNATURES = [
+  { ext: "png", parts: [[0, [0x89, ...ascii("PNG"), 0x0d, 0x0a, 0x1a, 0x0a]]] },
+  { ext: "jpg", parts: [[0, [0xff, 0xd8, 0xff]]] },
+  { ext: "gif", parts: [[0, ascii("GIF8")]] },
+  { ext: "bmp", parts: [[0, ascii("BM")]] },
+  // Endian-dependent: "II" + 42 little, "MM" + 42 big.
+  { ext: "tiff", parts: [[0, [...ascii("II"), 0x2a, 0x00]]] },
+  { ext: "tiff", parts: [[0, [...ascii("MM"), 0x00, 0x2a]]] },
+  // RIFF<4-byte size>WEBP — the format tag sits past the container header.
+  { ext: "webp", parts: [[0, ascii("RIFF")], [8, ascii("WEBP")]] },
+];
+
+// Identify an image from its BYTES, ignoring any declared MIME type. Returns null
+// when nothing matches (an SVG, or a format this system never ingests) so the
+// caller keeps its MIME-derived guess rather than inventing one.
+//
+// Why sniff at all: the declared type is only as good as the upstream
+// `Content-Type`, and it is demonstrably wrong in the wild — a 1024x1024 PNG in
+// the corpus arrived as `data:image/jpeg`, so the CLI wrote PNG bytes into a
+// `.jpg` file. A wrong extension is not cosmetic here: the asset is referenced
+// from slide JSX as `<img src>` and the renderer picks its decoder from the file
+// type, so a mislabelled asset can fail to render in the .pptx.
+export function extFromBytes(buf) {
+  if (!buf || buf.length < 2) return null;
+  for (const { ext, parts } of MAGIC_SIGNATURES) {
+    const matched = parts.every(([offset, bytes]) => {
+      if (buf.length < offset + bytes.length) return false;
+      return bytes.every((b, i) => buf[offset + i] === b);
+    });
+    if (matched) return ext;
+  }
+  return null;
+}
+
+// The extension to write bytes under: what the bytes ARE beats what the wire
+// claims. SVG is exempt — it is XML with no magic number, and the SVG path is
+// already gated on `svgMarkup` being present.
+export function resolveAssetExt(mimeType, buf) {
+  const declared = extFromMime(mimeType);
+  if (declared === "svg") return declared;
+  return extFromBytes(buf) ?? declared;
+}
+
+// Stream one result into assetsDir via the add-in's streaming route.
+//
+// Returns the same shape as `downloadOneResult`, or null when the paired add-in
+// has no streaming route (404/501) so the caller can fall back to the capped
+// ack path. A real failure (bad selection, dead source) throws.
+async function streamOneResult({
+  client,
+  presId,
+  backendURL,
+  searchId,
+  assetsDir,
+  selection,
+  iconColor,
+}) {
+  if (typeof client.engineDownloadToFile !== "function") return null;
+  // Write under a provisional name: the true extension is only knowable from the
+  // bytes, and buffering the image just to sniff its header would defeat the
+  // purpose of streaming.
+  const tempPath = path.join(assetsDir, `.engine-${searchId}-${selection}.part`);
+  let res;
+  try {
+    res = await client.engineDownloadToFile({
+      presId,
+      backendURL,
+      searchId,
+      selection,
+      destPath: tempPath,
+      iconColor: iconColor ?? null,
+      onProgress: createTransferProgress(`downloading result ${selection}`),
+    });
+  } catch (err) {
+    fs.rmSync(tempPath, { force: true });
+    // Route absent → this add-in predates streaming; let the caller fall back.
+    // A 404 that carries a machine code is the ROUTE talking (`unknown_search`
+    // for a stale selection), not Express saying "no such path" — retrying that
+    // on the capped path would just fail again, more slowly.
+    if ((err?.status === 404 && !err?.code) || err?.status === 501) return null;
+    throw err;
+  }
+
+  try {
+    if (res?.svgMarkup) {
+      // SVG arrives inline, not as a stream.
+      fs.rmSync(tempPath, { force: true });
+      const filename = `engine-${searchId}-${selection}.svg`;
+      const target = path.join(assetsDir, filename);
+      fs.writeFileSync(target, res.svgMarkup, "utf8");
+      return {
+        selection,
+        path: target,
+        reference: `./assets/${filename}`,
+        mimeType: res.mimeType ?? "image/svg+xml",
+        recolor: describeRecolor(res.svgMarkup, res.mimeType, iconColor ?? null),
+        size: svgSizeFromMarkup(res.svgMarkup),
+      };
+    }
+
+    if (!res?.bytesWritten) {
+      throw new Error("stream produced no bytes");
+    }
+    // Read only the leading header block, not the whole file: enough to sniff
+    // the format AND to reach a JPEG's SOF segment past its EXIF/ICC blocks.
+    const fd = fs.openSync(tempPath, "r");
+    const probeBytes = Math.min(DIMENSION_PROBE_BYTES, res.bytesWritten);
+    const header = Buffer.alloc(probeBytes);
+    let read = 0;
+    try {
+      read = fs.readSync(fd, header, 0, probeBytes, 0);
+    } finally {
+      fs.closeSync(fd);
+    }
+    const probe = header.subarray(0, read);
+    const ext = resolveAssetExt(res.mimeType, probe);
+    const filename = `engine-${searchId}-${selection}.${ext}`;
+    const target = path.join(assetsDir, filename);
+    fs.renameSync(tempPath, target);
+    return {
+      selection,
+      path: target,
+      reference: `./assets/${filename}`,
+      mimeType: res.mimeType ?? null,
+      recolor: describeRecolor(null, res.mimeType, iconColor ?? null),
+      size: imageSizeFromBuffer(probe),
+    };
+  } catch (err) {
+    fs.rmSync(tempPath, { force: true });
+    throw err;
+  }
+}
+
 // Download one chosen engine result via the bridge and write it into assetsDir.
-// Returns { selection, path, reference, mimeType, recolor }. Throws on failure
+// Returns { selection, path, reference, mimeType, recolor, size }. Throws on failure
 // so callers can Promise.allSettled a batch without one bad selection sinking
 // the rest.
 export async function downloadOneResult({
@@ -55,6 +244,23 @@ export async function downloadOneResult({
   selection,
   iconColor,
 }) {
+  // Preferred path: stream via the add-in server, which is unbounded in image
+  // size. The extension can only be decided once bytes exist, so stream to a
+  // temp name first and rename — cheaper than buffering a 100 MB image to sniff
+  // its header.
+  const streamed = await streamOneResult({
+    client,
+    presId,
+    backendURL,
+    searchId,
+    assetsDir,
+    selection,
+    iconColor,
+  });
+  if (streamed) return streamed;
+
+  // Fallback for an add-in that predates the streaming route: bytes ride the
+  // pane's Socket.IO ack, capped by its 10 MB frame limit.
   const res = await client.engineDownload({
     presId,
     backendURL,
@@ -63,16 +269,28 @@ export async function downloadOneResult({
     iconColor: iconColor ?? null,
   });
   if (!res?.ok) {
-    throw new Error(res?.error ?? "download failed");
+    // `payload_too_large` is the add-in refusing an ack the relay's Socket.IO
+    // frame cap would otherwise DROP — which previously surfaced as an
+    // unexplained "task pane did not respond" timeout. Its message already
+    // carries the sizes, so pass it through as the cause rather than restating.
+    const err = new Error(res?.error ?? "download failed");
+    if (res?.code) err.code = res.code;
+    throw err;
   }
-  const ext = extFromMime(res.mimeType);
+  // Decode first so the extension can be decided by the BYTES, not by a
+  // Content-Type the engine inherited from upstream and may have wrong.
+  const bytes =
+    typeof res.base64 === "string" && res.base64.length > 0
+      ? Buffer.from(res.base64, "base64")
+      : null;
+  const ext = resolveAssetExt(res.mimeType, bytes);
   const filename = `engine-${searchId}-${selection}.${ext}`;
   const target = path.join(assetsDir, filename);
   if (res.svgMarkup && ext === "svg") {
     // The (possibly recoloured) SVG markup is the canonical asset.
     fs.writeFileSync(target, res.svgMarkup, "utf8");
-  } else if (typeof res.base64 === "string" && res.base64.length > 0) {
-    fs.writeFileSync(target, Buffer.from(res.base64, "base64"));
+  } else if (bytes) {
+    fs.writeFileSync(target, bytes);
   } else if (res.svgMarkup) {
     // SVG bytes arrived only as markup (mimeType lacked an svg hint).
     fs.writeFileSync(target, res.svgMarkup, "utf8");
@@ -85,5 +303,11 @@ export async function downloadOneResult({
     reference: `./assets/${filename}`,
     mimeType: res.mimeType,
     recolor: describeRecolor(res.svgMarkup ?? null, res.mimeType, iconColor ?? null),
+    // Measured from the asset actually written: SVG user units for markup,
+    // pixels for a raster. Null when the format carries no readable header.
+    size:
+      ext === "svg"
+        ? svgSizeFromMarkup(res.svgMarkup ?? null)
+        : imageSizeFromBuffer(bytes),
   };
 }

package/src/bridge/image-dimensions.mjs

@@ -0,0 +1,181 @@
+// Intrinsic pixel dimensions of an image, read from its own header bytes.
+//
+// Why here and not from the add-in: the engine wire carries a MIME type and the
+// bytes, never a size, and both transfer paths (the streaming route and the
+// capped ack fallback) end with the file already on disk. Measuring locally
+// therefore works against every add-in version with no wire change, and it
+// measures the asset the deck will actually reference rather than a thumbnail.
+//
+// Consumers: `slidemind download-result` reports the size so the agent can size
+// an `<img>` box to the real aspect ratio instead of guessing one.
+
+// Scan far enough into a JPEG to reach its first SOF segment past the EXIF/ICC
+// blocks that routinely occupy the first few dozen KB.
+export const DIMENSION_PROBE_BYTES = 128 * 1024;
+
+const ascii = (s) => [...s].map((c) => c.charCodeAt(0));
+
+const startsWith = (buf, offset, bytes) =>
+  buf.length >= offset + bytes.length && bytes.every((b, i) => buf[offset + i] === b);
+
+function pngSize(buf) {
+  // 8-byte signature, then the IHDR chunk: length(4) type(4) width(4) height(4).
+  if (!startsWith(buf, 12, ascii("IHDR"))) return null;
+  if (buf.length < 24) return null;
+  return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+}
+
+function gifSize(buf) {
+  if (buf.length < 10) return null;
+  return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) };
+}
+
+function bmpSize(buf) {
+  if (buf.length < 26) return null;
+  const headerSize = buf.readUInt32LE(14);
+  // BITMAPCOREHEADER is 16-bit; every later DIB header is 32-bit signed, with a
+  // negative height meaning a top-down bitmap.
+  if (headerSize === 12) {
+    return { width: buf.readUInt16LE(18), height: buf.readUInt16LE(20) };
+  }
+  if (buf.length < 27) return null;
+  return { width: Math.abs(buf.readInt32LE(18)), height: Math.abs(buf.readInt32LE(22)) };
+}
+
+function webpSize(buf) {
+  // RIFF<size>WEBP, then one of three chunk flavours.
+  if (buf.length < 30) return null;
+  const chunk = String.fromCharCode(buf[12], buf[13], buf[14], buf[15]);
+  if (chunk === "VP8 ") {
+    // Lossy: 3-byte frame tag, 3-byte sync code, then 14-bit width/height.
+    return {
+      width: buf.readUInt16LE(26) & 0x3fff,
+      height: buf.readUInt16LE(28) & 0x3fff,
+    };
+  }
+  if (chunk === "VP8L") {
+    // Lossless: signature byte 0x2f, then 14 bits width-1 and 14 bits height-1.
+    if (buf[20] !== 0x2f) return null;
+    const bits = buf.readUInt32LE(21);
+    return { width: (bits & 0x3fff) + 1, height: ((bits >> 14) & 0x3fff) + 1 };
+  }
+  if (chunk === "VP8X") {
+    // Extended: canvas size as two 24-bit little-endian values, minus one.
+    return {
+      width: buf.readUIntLE(24, 3) + 1,
+      height: buf.readUIntLE(27, 3) + 1,
+    };
+  }
+  return null;
+}
+
+// Markers that carry no payload and so must not be length-skipped.
+const JPEG_STANDALONE = new Set([0x01, 0xd8, 0xd9, 0xd0, 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7]);
+// Every Start-Of-Frame flavour (baseline, progressive, lossless, …). The three
+// holes are DHT (0xc4), JPG extension (0xc8) and DAC (0xcc), which are not SOFs.
+const isJpegSof = (m) => m >= 0xc0 && m <= 0xcf && m !== 0xc4 && m !== 0xc8 && m !== 0xcc;
+
+function jpegSize(buf) {
+  let pos = 2; // past SOI
+  while (pos + 3 < buf.length) {
+    if (buf[pos] !== 0xff) {
+      // Resync: fill bytes (0xff) and the odd stray byte are legal between
+      // segments; anything else means the header is not parseable.
+      pos++;
+      continue;
+    }
+    let marker = buf[pos + 1];
+    // Any number of 0xff fill bytes may precede the marker itself.
+    let markerPos = pos + 1;
+    while (marker === 0xff && markerPos + 1 < buf.length) {
+      marker = buf[++markerPos];
+    }
+    if (JPEG_STANDALONE.has(marker)) {
+      pos = markerPos + 1;
+      continue;
+    }
+    if (markerPos + 3 >= buf.length) return null;
+    const length = buf.readUInt16BE(markerPos + 1);
+    if (isJpegSof(marker)) {
+      // SOF payload: precision(1) height(2) width(2).
+      if (markerPos + 7 >= buf.length) return null;
+      return {
+        height: buf.readUInt16BE(markerPos + 4),
+        width: buf.readUInt16BE(markerPos + 6),
+      };
+    }
+    if (length < 2) return null;
+    pos = markerPos + 1 + length;
+  }
+  return null;
+}
+
+/**
+ * Intrinsic pixel size of a raster image, read from its header bytes.
+ *
+ * Takes the same "the bytes beat the declared type" stance as `extFromBytes`
+ * (engine-download.mjs): the format is sniffed, never taken from a MIME type.
+ * Returns null for anything unrecognised (TIFF, a truncated header, an SVG) so
+ * the caller reports "unknown" rather than a fabricated size.
+ */
+export function imageSizeFromBuffer(buf) {
+  if (!buf || buf.length < 16) return null;
+  let size = null;
+  if (startsWith(buf, 0, [0x89, ...ascii("PNG"), 0x0d, 0x0a, 0x1a, 0x0a])) size = pngSize(buf);
+  else if (startsWith(buf, 0, [0xff, 0xd8, 0xff])) size = jpegSize(buf);
+  else if (startsWith(buf, 0, ascii("GIF8"))) size = gifSize(buf);
+  else if (startsWith(buf, 0, ascii("BM"))) size = bmpSize(buf);
+  else if (startsWith(buf, 0, ascii("RIFF")) && startsWith(buf, 8, ascii("WEBP"))) size = webpSize(buf);
+  if (!size) return null;
+  if (!Number.isFinite(size.width) || !Number.isFinite(size.height)) return null;
+  if (size.width <= 0 || size.height <= 0) return null;
+  return size;
+}
+
+/**
+ * Intrinsic size of an SVG, in its own user units.
+ *
+ * `width`/`height` win when both are plain lengths; otherwise the viewBox
+ * supplies the aspect ratio (the common case for icon sets, which size
+ * themselves from CSS and carry only a viewBox). Percentage widths are ignored
+ * for the same reason — they describe the container, not the graphic.
+ */
+export function svgSizeFromMarkup(markup) {
+  if (typeof markup !== "string" || markup.length === 0) return null;
+  // Only the opening <svg …> tag may contribute; a nested <symbol width=…>
+  // further down must not be mistaken for the root size.
+  const openTag = /<svg\b[^>]*>/i.exec(markup)?.[0];
+  if (!openTag) return null;
+
+  const length = (name) => {
+    const m = new RegExp(`\\b${name}\\s*=\\s*["']?\\s*([\\d.]+)\\s*([a-z%]*)`, "i").exec(openTag);
+    if (!m) return null;
+    // Only unitless user units and `px` are a pixel count. `%` sizes the
+    // container, not the graphic, and physical units (mm/pt/in) would need a DPI
+    // — both fall through to the viewBox, which always states the true ratio.
+    const unit = m[2].toLowerCase();
+    if (unit !== "" && unit !== "px") return null;
+    const n = Number.parseFloat(m[1]);
+    return Number.isFinite(n) && n > 0 ? n : null;
+  };
+
+  const width = length("width");
+  const height = length("height");
+  if (width && height) return { width, height };
+
+  const viewBox = /\bviewBox\s*=\s*["']?\s*([-\d.\s,]+)/i.exec(openTag);
+  if (viewBox) {
+    const parts = viewBox[1].trim().split(/[\s,]+/).map(Number.parseFloat);
+    if (parts.length === 4 && parts.every(Number.isFinite) && parts[2] > 0 && parts[3] > 0) {
+      return { width: width ?? parts[2], height: height ?? parts[3] };
+    }
+  }
+  return null;
+}
+
+/** `1200×800` for display, or null when the size could not be read. */
+export function formatSize(size) {
+  if (!size) return null;
+  const round = (n) => (Number.isInteger(n) ? n : Math.round(n * 100) / 100);
+  return `${round(size.width)}×${round(size.height)}`;
+}

package/src/builders/build.mjs

@@ -945,31 +945,61 @@ function openerChain(target) {
   return [{ cmd: "xdg-open", args: [target] }];
 }
 
+// How long to give a platform opener to exit before assuming it handed the URL
+// off successfully. `open`/`xdg-open`/`start` all exit within milliseconds; an
+// opener still running after this window is treated as launched, not failed.
+const OPENER_EXIT_GRACE_MS = 2000;
+
 // Open a local file path OR an http URL in the user's default browser, trying
-// each platform opener in turn. This is fire-and-forget and must NEVER crash:
-// if the opener binary is missing (e.g. a headless Linux box with no xdg-open)
-// the spawned child would otherwise emit an unhandled 'error' and take down the
-// whole CLI. We degrade gracefully — on exhausting the chain we just print the
-// target for the user to open manually.
-export function openInBrowser(target) {
+// each platform opener in turn. Must NEVER crash: if the opener binary is
+// missing (e.g. a headless Linux box with no xdg-open) the spawned child would
+// otherwise emit an unhandled 'error' and take down the whole CLI.
+//
+// Resolves `true` when an opener plausibly launched (exit 0, or still running
+// after the grace window), `false` when the whole chain failed — missing
+// binaries AND nonzero exits both advance the chain, so a present-but-broken
+// `xdg-open` (headless box, no browser) is reported as a failure instead of
+// silently swallowed. Never rejects. On `false` the target is printed for the
+// user to open manually unless `quiet` — callers with their own messaging (the
+// review/plan gates) pass quiet:true and speak for themselves.
+export function openInBrowser(target, { quiet = false } = {}) {
   const chain = openerChain(target);
-  const tryAt = (i) => {
-    if (i >= chain.length) {
-      process.stderr.write(`couldn't open a browser — open ${target} manually\n`);
-      return;
-    }
-    const { cmd, args } = chain[i];
-    let child;
-    try {
-      child = spawn(cmd, args, { stdio: "ignore", detached: true });
-    } catch {
-      tryAt(i + 1);
-      return;
-    }
-    child.on("error", () => tryAt(i + 1));
-    child.unref();
-  };
-  tryAt(0);
+  return new Promise((resolve) => {
+    const tryAt = (i) => {
+      if (i >= chain.length) {
+        if (!quiet) {
+          process.stderr.write(`couldn't open a browser — open ${target} manually\n`);
+        }
+        resolve(false);
+        return;
+      }
+      const { cmd, args } = chain[i];
+      let child;
+      try {
+        child = spawn(cmd, args, { stdio: "ignore", detached: true });
+      } catch {
+        tryAt(i + 1);
+        return;
+      }
+      let settled = false;
+      const settle = (ok) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (ok) resolve(true);
+        else tryAt(i + 1);
+      };
+      // Still running after the grace window ⇒ it took the URL; don't hold the
+      // caller hostage to an opener that lingers. unref'd so it can't keep the
+      // process alive either way.
+      const timer = setTimeout(() => settle(true), OPENER_EXIT_GRACE_MS);
+      if (timer.unref) timer.unref();
+      child.on("error", () => settle(false));
+      child.on("exit", (code) => settle(code === 0));
+      child.unref();
+    };
+    tryAt(0);
+  });
 }
 
 function parseArgs(argv) {