@minhvuong/pirate-storage-preview-browser 0.1.0

package/README.md

@@ -0,0 +1,9 @@
+# @minhvuong/pirate-storage-preview-browser
+
+Optional browser preview generator for `@minhvuong/pirate-storage`.
+
+This is the low-memory Web Worker implementation extracted from the Discord demo. It reads JPEG
+or PNG dimensions without decoding the complete source at full resolution, requests a reduced
+decode when supported, and encodes a JPEG below the configured attachment target.
+
+It is deliberately separate from core so server-only and non-image consumers do not install it.

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import type { GeneratedPreview, PreviewGenerator } from "@minhvuong/pirate-storage";
+import type { ImagePreviewMetrics, PreviewProgress } from "./types";
+export * from "./types";
+export declare const DISCORD_PREVIEW_LIMIT_BYTES: number;
+export declare const DISCORD_PREVIEW_TARGET_BYTES: number;
+export interface PreparedImagePreview extends GeneratedPreview {
+    metrics: ImagePreviewMetrics;
+    metadata: {
+        metrics: ImagePreviewMetrics;
+    };
+}
+export interface BrowserImagePreviewOptions {
+    id?: string;
+    /** Generate only for files larger than this. Defaults to Discord's recommended 8 MiB part. */
+    thresholdBytes?: number;
+    targetBytes?: number;
+    workerFactory?: () => Worker;
+}
+export declare function createBrowserImagePreview(options?: BrowserImagePreviewOptions): PreviewGenerator;
+export declare function prepareImagePreview(file: Blob, filename: string, options?: {
+    targetBytes?: number;
+    signal?: AbortSignal;
+    onProgress?: (progress: PreviewProgress) => void;
+    workerFactory?: () => Worker;
+}): Promise<PreparedImagePreview>;
+/** Compatibility name used by the original Discord demo. */
+export declare function prepareDiscordImagePreview(file: File, options?: {
+    signal?: AbortSignal;
+    onProgress?: (progress: PreviewProgress) => void;
+    workerFactory?: () => Worker;
+}): Promise<PreparedImagePreview>;

package/dist/index.js

@@ -0,0 +1,109 @@
+// src/index.ts
+var DISCORD_PREVIEW_LIMIT_BYTES = 8 * 1024 * 1024;
+var DISCORD_PREVIEW_TARGET_BYTES = DISCORD_PREVIEW_LIMIT_BYTES - 128 * 1024;
+function createBrowserImagePreview(options = {}) {
+  const thresholdBytes = positiveInteger(options.thresholdBytes ?? DISCORD_PREVIEW_LIMIT_BYTES, "thresholdBytes");
+  const targetBytes = positiveInteger(options.targetBytes ?? DISCORD_PREVIEW_TARGET_BYTES, "targetBytes");
+  if (targetBytes >= thresholdBytes) {
+    throw new Error("targetBytes must be smaller than thresholdBytes");
+  }
+  return {
+    id: options.id ?? "browser-image",
+    supports(source) {
+      return Boolean(source.blob) && source.size > thresholdBytes && isSupportedImage(source.contentType, source.name);
+    },
+    async generate(source, context) {
+      if (!source.blob || !isSupportedImage(source.contentType, source.name))
+        return;
+      return prepareImagePreview(source.blob, source.name, {
+        targetBytes,
+        signal: context.signal,
+        onProgress: context.onProgress,
+        workerFactory: options.workerFactory
+      });
+    }
+  };
+}
+function prepareImagePreview(file, filename, options = {}) {
+  const targetBytes = positiveInteger(options.targetBytes ?? DISCORD_PREVIEW_TARGET_BYTES, "targetBytes");
+  return new Promise((resolve, reject) => {
+    if (options.signal?.aborted) {
+      reject(abortError());
+      return;
+    }
+    const worker = options.workerFactory?.() ?? new Worker(new URL("./worker.js", import.meta.url), { type: "module" });
+    let settled = false;
+    const finish = () => {
+      worker.terminate();
+      options.signal?.removeEventListener("abort", handleAbort);
+    };
+    const handleAbort = () => {
+      if (settled)
+        return;
+      settled = true;
+      finish();
+      reject(abortError());
+    };
+    options.signal?.addEventListener("abort", handleAbort, { once: true });
+    worker.addEventListener("message", (event) => {
+      if (settled)
+        return;
+      const message = event.data;
+      if (message.type === "progress") {
+        options.onProgress?.(message.progress);
+        return;
+      }
+      settled = true;
+      finish();
+      if (message.type === "error") {
+        reject(new Error(message.message));
+        return;
+      }
+      const previewName = `${stripExtension(filename)}.preview.jpg`;
+      resolve({
+        file: new File([message.blob], previewName, {
+          type: "image/jpeg",
+          lastModified: Date.now()
+        }),
+        width: message.metrics.outputWidth,
+        height: message.metrics.outputHeight,
+        metrics: message.metrics,
+        metadata: { metrics: message.metrics }
+      });
+    });
+    worker.addEventListener("error", (event) => {
+      if (settled)
+        return;
+      settled = true;
+      finish();
+      reject(new Error(event.message || "The image preview worker crashed"));
+    });
+    worker.postMessage({ file, targetBytes });
+  });
+}
+function prepareDiscordImagePreview(file, options = {}) {
+  return prepareImagePreview(file, file.name, options);
+}
+function isSupportedImage(contentType, filename) {
+  return contentType === "image/jpeg" || contentType === "image/png" || /\.(?:jpe?g|png)$/i.test(filename);
+}
+function stripExtension(filename) {
+  const lastDot = filename.lastIndexOf(".");
+  return lastDot > 0 ? filename.slice(0, lastDot) : filename;
+}
+function positiveInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+  return value;
+}
+function abortError() {
+  return new DOMException("Preview generation was cancelled", "AbortError");
+}
+export {
+  prepareImagePreview,
+  prepareDiscordImagePreview,
+  createBrowserImagePreview,
+  DISCORD_PREVIEW_TARGET_BYTES,
+  DISCORD_PREVIEW_LIMIT_BYTES
+};

package/dist/types.d.ts

@@ -0,0 +1,36 @@
+export type PreviewStage = "inspect" | "decode" | "draw" | "encode";
+export interface PreviewProgress {
+    percentage: number;
+    stage: PreviewStage;
+}
+export interface ImagePreviewMetrics {
+    decoder: "image-bitmap" | "webcodecs";
+    sourceBytes: number;
+    sourceWidth: number;
+    sourceHeight: number;
+    outputBytes: number;
+    outputWidth: number;
+    outputHeight: number;
+    quality: number;
+    elapsedMs: number;
+    encodeAttempts: number;
+    decodedSurfaceBytes: number;
+    fullDecodeBytes: number;
+    estimatedPeakWorkingBytes: number;
+    targetBytes: number;
+}
+export type PreviewWorkerRequest = {
+    file: Blob;
+    targetBytes: number;
+};
+export type PreviewWorkerResponse = {
+    type: "progress";
+    progress: PreviewProgress;
+} | {
+    type: "result";
+    blob: Blob;
+    metrics: ImagePreviewMetrics;
+} | {
+    type: "error";
+    message: string;
+};

package/dist/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/worker.js

@@ -0,0 +1,212 @@
+// src/worker.ts
+var worker = globalThis;
+var JPEG_HEADER_READ_BYTES = 2 * 1024 * 1024;
+var MIN_QUALITY = 0.72;
+var INITIAL_QUALITY = 0.9;
+var MAX_QUALITY = 0.98;
+var TARGET_TOLERANCE = 0.04;
+var MAX_ENCODE_ATTEMPTS = 4;
+var JPEG_DCT_SCALES = [1 / 8, 1 / 4, 3 / 8, 1 / 2, 5 / 8, 3 / 4, 7 / 8];
+worker.addEventListener("message", (event) => {
+  createPreview(event.data).catch((error) => {
+    post({
+      type: "error",
+      message: error instanceof Error ? error.message : "Could not create the image preview"
+    });
+  });
+});
+async function createPreview({ file, targetBytes }) {
+  const startedAt = performance.now();
+  postProgress("inspect", 4);
+  assertWorkerSupport();
+  const source = await readImageDimensions(file);
+  const idealScale = chooseInitialScale(file.size, targetBytes);
+  const isJpeg = file.type === "image/jpeg";
+  const scale = isJpeg ? snapToJpegDctScale(idealScale) : idealScale;
+  const outputWidth = outputDimension(source.width * scale, isJpeg);
+  const outputHeight = outputDimension(source.height * scale, isJpeg);
+  postProgress("decode", 14);
+  const decoded = await decodeReduced(file, outputWidth, outputHeight);
+  postProgress("draw", 48);
+  const canvas = new OffscreenCanvas(outputWidth, outputHeight);
+  const context = canvas.getContext("2d", { alpha: false });
+  if (!context) {
+    decoded.close();
+    throw new Error("This browser could not create a 2D preview canvas");
+  }
+  context.fillStyle = "#ffffff";
+  context.fillRect(0, 0, outputWidth, outputHeight);
+  context.drawImage(decoded.image, 0, 0, outputWidth, outputHeight);
+  decoded.close();
+  const { candidate, attempts } = await encodeNearTarget(canvas, targetBytes);
+  const decodedSurfaceBytes = outputWidth * outputHeight * 4;
+  const metrics = {
+    decoder: decoded.decoder,
+    sourceBytes: file.size,
+    sourceWidth: source.width,
+    sourceHeight: source.height,
+    outputBytes: candidate.blob.size,
+    outputWidth,
+    outputHeight,
+    quality: candidate.quality,
+    elapsedMs: performance.now() - startedAt,
+    encodeAttempts: attempts,
+    decodedSurfaceBytes,
+    fullDecodeBytes: source.width * source.height * 4,
+    estimatedPeakWorkingBytes: file.size + decodedSurfaceBytes * 2 + candidate.blob.size,
+    targetBytes
+  };
+  canvas.width = 1;
+  canvas.height = 1;
+  postProgress("encode", 100);
+  post({ type: "result", blob: candidate.blob, metrics });
+}
+async function encodeNearTarget(canvas, targetBytes) {
+  let low = MIN_QUALITY;
+  let high = MAX_QUALITY;
+  let quality = INITIAL_QUALITY;
+  let best = null;
+  let smallest = null;
+  for (let attempt = 1;attempt <= MAX_ENCODE_ATTEMPTS; attempt += 1) {
+    postProgress("encode", 55 + Math.round(attempt / MAX_ENCODE_ATTEMPTS * 40));
+    const blob = await canvas.convertToBlob({ type: "image/jpeg", quality });
+    const candidate = { blob, quality };
+    if (!smallest || blob.size < smallest.blob.size)
+      smallest = candidate;
+    if (blob.size <= targetBytes && (!best || blob.size > best.blob.size))
+      best = candidate;
+    const utilization = blob.size / targetBytes;
+    if (utilization <= 1 && utilization >= 1 - TARGET_TOLERANCE) {
+      return { candidate, attempts: attempt };
+    }
+    if (blob.size > targetBytes)
+      high = quality;
+    else
+      low = quality;
+    quality = Math.round((low + high) / 2 * 1000) / 1000;
+  }
+  if (best)
+    return { candidate: best, attempts: MAX_ENCODE_ATTEMPTS };
+  if (smallest) {
+    throw new Error(`The reduced image is still ${(smallest.blob.size / 1024 / 1024).toFixed(2)} MiB at minimum quality`);
+  }
+  throw new Error("The browser JPEG encoder returned no preview data");
+}
+function chooseInitialScale(sourceBytes, targetBytes) {
+  return Math.min(0.98, Math.max(0.05, Math.sqrt(targetBytes / sourceBytes) * 0.92));
+}
+function snapToJpegDctScale(idealScale) {
+  let selected = JPEG_DCT_SCALES[0];
+  for (const scale of JPEG_DCT_SCALES) {
+    if (scale > idealScale)
+      break;
+    selected = scale;
+  }
+  return selected;
+}
+function outputDimension(value, jpegDctScale) {
+  return jpegDctScale ? Math.max(1, Math.ceil(value)) : Math.max(2, Math.floor(value / 2) * 2);
+}
+function postProgress(stage, percentage) {
+  post({ type: "progress", progress: { stage, percentage } });
+}
+function post(message) {
+  worker.postMessage(message);
+}
+function assertWorkerSupport() {
+  if (typeof OffscreenCanvas !== "function") {
+    throw new Error("This browser needs OffscreenCanvas support");
+  }
+}
+async function decodeReduced(file, width, height) {
+  if (typeof ImageDecoder === "function" && await ImageDecoder.isTypeSupported(file.type)) {
+    const decoder = new ImageDecoder({
+      type: file.type,
+      data: file.stream(),
+      desiredWidth: width,
+      desiredHeight: height,
+      preferAnimation: false
+    });
+    try {
+      const result = await decoder.decode({ frameIndex: 0 });
+      return {
+        decoder: "webcodecs",
+        image: result.image,
+        close: () => {
+          result.image.close();
+          decoder.close();
+        }
+      };
+    } catch (error) {
+      decoder.close();
+      throw error;
+    }
+  }
+  if (typeof createImageBitmap !== "function") {
+    throw new Error("This browser needs WebCodecs ImageDecoder or createImageBitmap support");
+  }
+  const bitmap = await createImageBitmap(file, {
+    imageOrientation: "from-image",
+    resizeWidth: width,
+    resizeHeight: height,
+    resizeQuality: "high"
+  });
+  return { decoder: "image-bitmap", image: bitmap, close: () => bitmap.close() };
+}
+async function readImageDimensions(file) {
+  if (file.type === "image/jpeg")
+    return readJpegDimensions(file);
+  if (file.type === "image/png")
+    return readPngDimensions(file);
+  throw new Error("The low-memory preview path currently supports JPEG and PNG images");
+}
+async function readJpegDimensions(file) {
+  const bytes = new Uint8Array(await file.slice(0, Math.min(file.size, JPEG_HEADER_READ_BYTES)).arrayBuffer());
+  if (bytes[0] !== 255 || bytes[1] !== 216)
+    throw new Error("The selected file is not a JPEG");
+  let offset = 2;
+  while (offset + 8 < bytes.length) {
+    if (bytes[offset] !== 255) {
+      offset += 1;
+      continue;
+    }
+    while (bytes[offset] === 255)
+      offset += 1;
+    const marker = bytes[offset];
+    offset += 1;
+    if (marker === undefined || marker === 217 || marker === 218)
+      break;
+    if (marker === 1 || marker >= 208 && marker <= 215)
+      continue;
+    const segmentLength = readUint16(bytes, offset);
+    if (segmentLength < 2 || offset + segmentLength > bytes.length)
+      break;
+    if (isStartOfFrame(marker)) {
+      const height = readUint16(bytes, offset + 3);
+      const width = readUint16(bytes, offset + 5);
+      if (width > 0 && height > 0)
+        return { width, height };
+    }
+    offset += segmentLength;
+  }
+  throw new Error("Could not find JPEG dimensions in the first 2 MiB of metadata");
+}
+async function readPngDimensions(file) {
+  const bytes = new Uint8Array(await file.slice(0, 24).arrayBuffer());
+  const signature = [137, 80, 78, 71, 13, 10, 26, 10];
+  if (signature.some((value, index) => bytes[index] !== value)) {
+    throw new Error("The selected file is not a PNG");
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const width = view.getUint32(16);
+  const height = view.getUint32(20);
+  if (width <= 0 || height <= 0)
+    throw new Error("The PNG has invalid dimensions");
+  return { width, height };
+}
+function readUint16(bytes, offset) {
+  return (bytes[offset] ?? 0) << 8 | (bytes[offset + 1] ?? 0);
+}
+function isStartOfFrame(marker) {
+  return marker >= 192 && marker <= 207 && marker !== 196 && marker !== 200 && marker !== 204;
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@minhvuong/pirate-storage-preview-browser",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun build src/index.ts src/worker.ts --outdir dist --target browser --packages external && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@minhvuong/pirate-storage": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "catalog:"
+  }
+}