thumbnails.ts · Source

thumbnails.tspackages/storage/src/thumbnails.tsraw ← src14,362 B← Back to the app
1/**
2 * @factory/storage — thumbnail/preview planning (PURE) + a real, dependency-free
3 * PNG path (encoder + header parser + JPEG SOF scanner + metadata extraction).
4 *
5 * Two distinct jobs:
6 *
7 *  1. PLANNING — `planThumbnails(args)` decides WHICH artifacts the pipeline
8 *     must produce (keys in the `thumbs/` bucket layout, target widths).
9 *     Pure; the plan is the contract the TASK-0102 worker executes:
10 *
11 *       - images → 3 sizes (160 / 480 / 1280 px wide) in the SAME format,
12 *         keys `thumbs/{ws}/{fileId}/{size}/{safeName}.{ext}` (sizes skipped
13 *         when the source is smaller — never upscale)
14 *       - pdf    → first-page PNG (1280w)
15 *       - video  → first-frame PNG (1280w)
16 *       - audio/other → nothing (no thumbnail)
17 *
18 *  2. THE PNG PATH — a fully working, dependency-free PNG encoder
19 *     (IHDR/IDAT via node:zlib deflateSync/IEND + CRC32) with nearest-neighbor
20 *     downscaling, plus a PNG header parser and a JPEG SOF dimension scanner.
21 *     `computeMetadata(mime, buf, filenameHint)` is the metadata-extraction
22 *     pipeline step as a pure function over bytes:
23 *     mimeType (magic bytes) + dimensions + sha256 + isText.
24 *
25 * Real pixel work for non-PNG inputs (webp/avif/heic decode, pdf page-1
26 * render, video first frame) is the worker's job — it needs image codecs
27 * (sharp / pdfjs / ffmpeg) this package deliberately does not ship.
28 */
29 
30import { deflateSync } from "node:zlib";
31import { createHash } from "node:crypto";
32 
33import { isImageMime, isVideoMime, detectMimeType } from "./mime.js";
34import {
35  buildThumbKey,
36  THUMBNAIL_SIZES,
37  THUMBNAIL_SIZE_WIDTH,
38  type ThumbnailSize,
39} from "./keys.js";
40 
41// ── planning ────────────────────────────────────────────────────────────────
42 
43/** Output format per source image mime ("same format" — images only). */
44const IMAGE_OUTPUT_EXT: Record<string, string> = {
45  "image/png": "png",
46  "image/jpeg": "jpeg",
47  "image/webp": "webp",
48  "image/gif": "gif",
49  "image/bmp": "bmp",
50  "image/svg+xml": "png", // rasterized
51  "image/avif": "png", // rasterized
52  "image/heic": "png", // rasterized
53  "image/tiff": "png", // rasterized
54};
55 
56/**
57 * Decide which thumbnail artifacts to generate for a file (TASK-0102 §5):
58 *
59 *  - images      → 3 sizes (160/480/1280 px wide, same format, max 1280) at
60 *                  `thumbs/{ws}/{fileId}/{size}/{safeName}.{ext}`; a size is
61 *                  skipped when the source width is ≤ the target (no upscale).
62 *  - pdf         → one first-page PNG (1280w) at `thumbs/{ws}/{fileId}/1280/…`.
63 *  - video       → one first-frame PNG (1280w).
64 *  - audio/other → [] (no thumbnail — `File.thumbnailKey` stays null).
65 *
66 * PURE — same args ⇒ same plan, no clock, no I/O.
67 */
68export function planThumbnails(args: {
69  mime: string;
70  workspaceId: string;
71  fileId: string;
72  /** Original file name (sanitized inside {@link buildThumbKey}). */
73  name: string;
74  /** Source image width in px (skips sizes that would upscale). */
75  sourceWidth?: number;
76}): Array<{
77  size: ThumbnailSize;
78  /** S3 key in the `thumbs` bucket. */
79  key: string;
80  /** Target width in px. */
81  targetWidth: number;
82  /** Output MIME. */
83  mime: string;
84  /** What the worker must do to produce the artifact. */
85  source: "image" | "pdf-page-1" | "video-first-frame";
86}> {
87  const { mime, workspaceId, fileId, sourceWidth } = args;
88 
89  // Artifact name = source STEM + artifact extension: the original
90  // extension is REPLACED by the output format (`c.jpg` → `c.jpeg`,
91  // `doc.pdf` → `doc.png`) — never appended after it.
92  const dot = args.name.lastIndexOf(".");
93  const stem = dot > 0 ? args.name.slice(0, dot) : args.name;
94 
95  if (isImageMime(mime)) {
96    const ext = IMAGE_OUTPUT_EXT[mime] ?? "png";
97    const plan: ReturnType<typeof planThumbnails> = [];
98    for (const size of THUMBNAIL_SIZES) {
99      const width = THUMBNAIL_SIZE_WIDTH[size];
100      if (sourceWidth !== undefined && sourceWidth > 0 && sourceWidth <= width) {
101        continue; // never upscale
102      }
103      plan.push({
104        size,
105        key: buildThumbKey({ workspaceId, fileId, size, name: stem, ext }),
106        targetWidth: width,
107        mime,
108        source: "image",
109      });
110    }
111    return plan;
112  }
113 
114  if (mime === "application/pdf") {
115    return [
116      {
117        size: "1280",
118        key: buildThumbKey({ workspaceId, fileId, size: "1280", name: stem, ext: "png" }),
119        targetWidth: THUMBNAIL_SIZE_WIDTH["1280"],
120        mime: "image/png",
121        source: "pdf-page-1",
122      },
123    ];
124  }
125 
126  if (isVideoMime(mime)) {
127    return [
128      {
129        size: "1280",
130        key: buildThumbKey({ workspaceId, fileId, size: "1280", name: stem, ext: "png" }),
131        targetWidth: THUMBNAIL_SIZE_WIDTH["1280"],
132        mime: "image/png",
133        source: "video-first-frame",
134      },
135    ];
136  }
137 
138  return []; // audio / documents / other: no thumbnail
139}
140 
141// ── CRC32 (PURE — needed for every PNG chunk) ──────────────────────────────
142 
143const CRC_TABLE: readonly number[] = (() => {
144  const table = new Array<number>(256);
145  for (let n = 0; n < 256; n++) {
146    let c = n;
147    for (let k = 0; k < 8; k++) {
148      c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
149    }
150    table[n] = c >>> 0;
151  }
152  return table;
153})();
154 
155/** Standard (IEEE 802.3) CRC-32, as used by PNG. */
156export function crc32(bytes: Uint8Array): number {
157  let c = 0xffffffff;
158  for (let i = 0; i < bytes.length; i++) {
159    c = CRC_TABLE[(c ^ bytes[i]!) & 0xff]! ^ (c >>> 8);
160  }
161  return (c ^ 0xffffffff) >>> 0;
162}
163 
164// ── PNG chunk plumbing ──────────────────────────────────────────────────────
165 
166function chunk(type: string, data: Uint8Array): Uint8Array {
167  const out = new Uint8Array(12 + data.length);
168  const view = new DataView(out.buffer);
169  view.setUint32(0, data.length);
170  const typeBytes = new TextEncoder().encode(type);
171  out.set(typeBytes, 4);
172  out.set(data, 8);
173  // CRC covers type + data.
174  view.setUint32(8 + data.length, crc32(out.subarray(4, 8 + data.length)));
175  return out;
176}
177 
178function concat(bytesList: readonly Uint8Array[]): Uint8Array {
179  let total = 0;
180  for (const b of bytesList) total += b.length;
181  const out = new Uint8Array(total);
182  let off = 0;
183  for (const b of bytesList) {
184    out.set(b, off);
185    off += b.length;
186  }
187  return out;
188}
189 
190/** IHDR payload: width, height, bitDepth, colorType, compression, filter, interlace. */
191function ihdrData(width: number, height: number, bitDepth = 8, colorType = 6): Uint8Array {
192  const data = new Uint8Array(13);
193  const view = new DataView(data.buffer);
194  view.setUint32(0, width);
195  view.setUint32(4, height);
196  view.setUint8(8, bitDepth);
197  view.setUint8(9, colorType);
198  view.setUint8(10, 0); // compression: deflate
199  view.setUint8(11, 0); // filter: none
200  view.setUint8(12, 0); // interlace: none
201  return data;
202}
203 
204const PNG_SIGNATURE = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
205 
206/**
207 * Encode an RGBA pixel buffer as PNG bytes.
208 *
209 * - Rows are prefixed with filter byte 0 (None) and deflated (node:zlib).
210 * - CRC32 on every chunk — output is a spec-valid, decodable PNG.
211 * - `colorType` 6 = truecolor+alpha (the default); use 2 (RGB) when the
212 *   buffer has no alpha channel.
213 */
214export function encodePng(rgba: Uint8Array, width: number, height: number): Uint8Array {
215  const bytesPerPx = 4;
216  const rowLen = width * bytesPerPx;
217  const raw = new Uint8Array((rowLen + 1) * height);
218  for (let y = 0; y < height; y++) {
219    raw[y * (rowLen + 1)] = 0; // filter: none
220    raw.set(rgba.subarray(y * rowLen, (y + 1) * rowLen), y * (rowLen + 1) + 1);
221  }
222  const idat = deflateSync(Buffer.from(raw), { level: 6 }) as Buffer;
223  return concat([
224    PNG_SIGNATURE,
225    chunk("IHDR", ihdrData(width, height)),
226    chunk("IDAT", new Uint8Array(idat.buffer, idat.byteOffset, idat.length)),
227    chunk("IEND", new Uint8Array(0)),
228  ]);
229}
230 
231// ── nearest-neighbor downscale ──────────────────────────────────────────────
232 
233/**
234 * Nearest-neighbor downscale of an RGBA buffer.
235 *
236 * Each output pixel picks the source pixel at
237 * `floor((x + 0.5) * srcW / dstW)` — the deterministic, library-free
238 * resampler. (A worker may later upgrade to area averaging; the PLAN is what
239 * is tested here, not the aesthetics.)
240 */
241export function nearestDownscale(
242  src: Uint8Array,
243  srcW: number,
244  srcH: number,
245  dstW: number,
246  dstH: number,
247): Uint8Array {
248  if (src.length < srcW * srcH * 4) {
249    throw new Error(`source buffer too small for ${srcW}x${srcH}`);
250  }
251  const dst = new Uint8Array(dstW * dstH * 4);
252  for (let y = 0; y < dstH; y++) {
253    const sy = Math.min(srcH - 1, Math.floor(((y + 0.5) * srcH) / dstH));
254    for (let x = 0; x < dstW; x++) {
255      const sx = Math.min(srcW - 1, Math.floor(((x + 0.5) * srcW) / dstW));
256      const si = (sy * srcW + sx) * 4;
257      const di = (y * dstW + x) * 4;
258      dst[di] = src[si]!;
259      dst[di + 1] = src[si + 1]!;
260      dst[di + 2] = src[si + 2]!;
261      dst[di + 3] = src[si + 3]!;
262    }
263  }
264  return dst;
265}
266 
267/**
268 * Downscale an RGBA buffer to `targetW` (height scaled proportionally,
269 * min 1×1) and encode as PNG. THE dependency-free thumbnail path.
270 */
271export function generatePngThumbnail(
272  rgba: Uint8Array,
273  srcW: number,
274  srcH: number,
275  targetW: number,
276): Uint8Array {
277  if (srcW < 1 || srcH < 1 || targetW < 1) {
278    throw new Error(`invalid dimensions: ${srcW}x${srcH} → ${targetW}`);
279  }
280  const scale = Math.min(1, targetW / srcW);
281  const dstW = Math.max(1, Math.round(srcW * scale));
282  const dstH = Math.max(1, Math.round(srcH * scale));
283  if (dstW === srcW && dstH === srcH) return encodePng(rgba, srcW, srcH);
284  const scaled = nearestDownscale(rgba, srcW, srcH, dstW, dstH);
285  return encodePng(scaled, dstW, dstH);
286}
287 
288// ── PNG header parser (inverse of the encoder — round-trip test) ───────────
289 
290export interface PngHeader {
291  width: number;
292  height: number;
293  bitDepth: number;
294  colorType: number;
295}
296 
297/**
298 * Parse width/height/bitDepth/colorType from a PNG file (signature + IHDR).
299 * Throws on anything that is not a PNG.
300 */
301export function parsePngHeader(buf: Uint8Array): PngHeader {
302  // Layout: signature(8) + [length(4) + type(4) + data(13) + crc(4)] → 33+ bytes
303  if (buf.length < 33) throw new Error("not a PNG: too short");
304  for (let i = 0; i < 8; i++) {
305    if (buf[i] !== PNG_SIGNATURE[i]) throw new Error("not a PNG: bad signature");
306  }
307  // First chunk type sits at 8 + 4 (after its length field).
308  const type = String.fromCharCode(buf[12]!, buf[13]!, buf[14]!, buf[15]!);
309  if (type !== "IHDR") throw new Error("not a PNG: first chunk is not IHDR");
310  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
311  return {
312    width: view.getUint32(16),
313    height: view.getUint32(20),
314    bitDepth: view.getUint8(24),
315    colorType: view.getUint8(25),
316  };
317}
318 
319// ── JPEG SOF scanner (dimensions without an image library) ─────────────────
320 
321/**
322 * Scan a JPEG byte stream for the first SOF0/SOF2 marker (0xC0/0xC2,
323 * baseline / progressive) and read width/height from its payload.
324 * Returns null when no SOF frame is present.
325 */
326export function parseJpegDimensions(buf: Uint8Array): { width: number; height: number } | null {
327  if (buf.length < 4 || buf[0] !== 0xff || buf[1] !== 0xd8) return null;
328  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
329  let i = 2;
330  while (i + 4 <= buf.length) {
331    if (buf[i] !== 0xff) {
332      i++;
333      continue;
334    }
335    const marker = buf[i + 1]!;
336    // Standalone markers (no payload).
337    if (marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd7) || marker === 0x01) {
338      i += 2;
339      continue;
340    }
341    // 0xFF fill bytes.
342    if (marker === 0xff) {
343      i++;
344      continue;
345    }
346    const len = view.getUint16(i + 2);
347    if ((marker === 0xc0 || marker === 0xc2) && i + 2 + len <= buf.length && len >= 7) {
348      return {
349        height: view.getUint16(i + 5),
350        width: view.getUint16(i + 7),
351      };
352    }
353    i += 2 + len;
354  }
355  return null;
356}
357 
358// ── metadata extraction (the pipeline step, as a pure function over bytes) ─
359 
360export interface ExtractedMetadata {
361  /** Detected MIME (magic bytes first — see mime.ts). */
362  mimeType: string;
363  /** True for image MIMEs. */
364  isImage?: boolean;
365  /** Width in px (PNG/JPEG only, when detected). */
366  width?: number;
367  /** Height in px (PNG/JPEG only, when detected). */
368  height?: number;
369  /** SHA-256 hex of the content. */
370  sha256: string;
371  /** True when the DETECTED MIME is text/* (incl. text inferred from the
372   *  filename extension — bytes always win over the claim). */
373  isText?: boolean;
374}
375 
376/**
377 * The metadata-extraction step as a pure function over bytes: detect MIME,
378 * pull PNG/JPEG dimensions, hash the content, flag text.
379 *
380 * `mime` is the CLAIMED type (kept for the call signature's intent); the
381 * bytes always win — a lying client is the normal case (AGENTS.md §20).
382 *
383 * Page count / duration are NOT extracted here — they need pdf/media codecs
384 * (worker, TASK-0102).
385 */
386export function computeMetadata(
387  mime: string,
388  buf: Uint8Array,
389  filenameHint?: string,
390): ExtractedMetadata {
391  void mime; // documented intent: detection from bytes overrides the claim
392  const detected = detectMimeType(buf, filenameHint);
393  const out: ExtractedMetadata = {
394    mimeType: detected.mime,
395    sha256: createHash("sha256").update(buf).digest("hex"),
396  };
397  if (isImageMime(detected.mime)) out.isImage = true;
398  if (detected.mime.startsWith("text/")) out.isText = true;
399 
400  if (detected.mime === "image/png") {
401    try {
402      const h = parsePngHeader(buf);
403      out.width = h.width;
404      out.height = h.height;
405    } catch {
406      // truncated/corrupt PNG — dimensions stay undefined
407    }
408  } else if (detected.mime === "image/jpeg") {
409    const dims = parseJpegDimensions(buf);
410    if (dims) {
411      out.width = dims.width;
412      out.height = dims.height;
413    }
414  }
415  return out;
416}
417