@raghuvamsi_rv/compresspics 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# compresspics
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The engine behind **[compresspics.org](https://compresspics.org)**.
+
+Fast, private photo compression that runs in the browser. Images are processed in a Web Worker using `OffscreenCanvas`, so the UI stays responsive and nothing gets uploaded. It has zero dependencies.
+
+- Scales the longest side down to 2560px (configurable), with step-down resampling to avoid moiré on fine textures
+- Outputs JPEG or WebP
+- Reads RAW files (**NEF, NRW, DNG, CR2, ARW, PEF**) by extracting the camera's embedded JPEG preview
+- Applies EXIF orientation, including RAW orientation
+- Includes TypeScript types
+
+## Install
+
+```sh
+npm install compresspics
+```
+
+## Usage
+
+```js
+import { compressImage } from 'compresspics';
+
+input.addEventListener('change', async () => {
+  const result = await compressImage(input.files[0], {
+    targetQuality: 0.8,      // 0.75 = smaller, 0.82 = more detail
+    maxDimension: 2560,
+    mimeType: 'image/jpeg',  // or 'image/webp'
+    onProgress: (percent, stage) => console.log(stage, percent),
+  });
+
+  console.log(`${(result.reduction * 100).toFixed(1)}% smaller`);
+  upload(result.file); // File named "<original>-compressed.jpg"
+});
+```
+
+### Result
+
+| Field | Description |
+| --- | --- |
+| `blob`, `file` | Compressed output |
+| `width`, `height` | Output dimensions |
+| `originalWidth`, `originalHeight` | Source dimensions (for RAW: embedded preview) |
+| `originalSize`, `compressedSize` | Size in bytes |
+| `reduction` | 0–1 fraction saved |
+| `source` | `'image'` or `'raw-preview'` |
+| `preview` | Extracted RAW preview blob, or `null` |
+
+Other exports: `DEFAULTS`, `RAW_EXTENSIONS`, `isRawFile(file)`, `terminate()`.
+
+## Notes
+
+- The package is browser-only. It needs `OffscreenCanvas` in workers, which is available in Chrome 69+, Firefox 105+ and Safari 16.4+. You can still import it during SSR, because the worker is only created on first use.
+- The worker is inlined as a Blob URL, so it works from any bundler or CDN. If your site has a Content Security Policy, it must allow `worker-src blob:`.
+- RAW output is the camera's own rendering of the shot. Edits made in Lightroom or similar tools aren't applied. Some DNGs only include a small preview.
+
+## Deploy to a Proxmox LXC
+
+The `Deploy site` GitHub Actions workflow builds the site and synchronizes `site/` to the LXC's web root whenever a commit is pushed to `main`. It can also be started manually from the repository's Actions tab. The separate `Test Server Connection` workflow can be run manually to verify SSH access before deploying.
+
+Create a Debian or Ubuntu LXC in Proxmox with a stable IP address. Use the distribution's default Nginx site in the LXC to serve `/var/www/html`; point your existing Nginx Proxy Manager proxy host at the LXC's address on port `80` and manage the public hostname and TLS certificate there. No custom Nginx site configuration is needed. Install rsync in the LXC. The current workflow uses a GitHub-hosted runner, so its SSH endpoint must be reachable from GitHub Actions. For an LXC kept private behind your LAN firewall, run a self-hosted GitHub Actions runner inside that network and change the workflow's `runs-on` value to that runner's label instead of exposing SSH publicly.
+
+In the container, create a dedicated account and a web root it can update:
+
+```sh
+apt update
+apt install -y nginx rsync
+useradd --create-home --shell /bin/bash deploy
+chown deploy:www-data /var/www/html
+chmod 0755 /var/www/html
+install -d -o deploy -g deploy -m 0700 /home/deploy/.ssh
+```
+
+Generate a dedicated Ed25519 key pair on a trusted machine, without a passphrase for unattended Actions use:
+
+```sh
+ssh-keygen -t ed25519 -C github-actions-compresspics -f compresspics-deploy
+```
+
+Add the contents of `compresspics-deploy.pub` to `/home/deploy/.ssh/authorized_keys` in the container, then secure it:
+
+```sh
+cat compresspics-deploy.pub >> /home/deploy/.ssh/authorized_keys
+chown deploy:deploy /home/deploy/.ssh/authorized_keys
+chmod 0600 /home/deploy/.ssh/authorized_keys
+```
+
+In the GitHub repository, add these Actions secrets:
+
+- `SSH_PRIVATE_KEY`: the full private key from `compresspics-deploy`
+- `SERVER_HOST`: the LXC's reachable public DNS name or IP address
+- `SERVER_USER`: `deploy`
+- `SERVER_PORT`: `2343`
+- `SERVER_KNOWN_HOSTS`: the LXC's SSH host-key entry, gathered and verified from a trusted network (for example, `ssh-keyscan -H -p 2343 <public-host>`)
+
+Add this Actions variable:
+
+- `DEPLOY_PATH`: `/var/www/html`
+
+In Nginx Proxy Manager, configure the domain to forward to the LXC's address on port `80` and manage the public TLS certificate there. Once the workflow secrets and variables are set, pushes to `main` deploy automatically. The workflow does not configure the Proxmox LXC, DNS, firewall, or Nginx Proxy Manager.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+export type OutputMimeType = 'image/jpeg' | 'image/webp';
+
+export interface CompressOptions {
+  /** Encoder quality 0–1. Default 0.8. */
+  targetQuality?: number;
+  /** Longest side in pixels. Default 2560. */
+  maxDimension?: number;
+  /** Default 'image/jpeg'. */
+  mimeType?: OutputMimeType;
+  onProgress?: (percent: number, stage: string) => void;
+}
+
+export interface CompressResult {
+  blob: Blob;
+  /** Compressed output as a File named `<original>-compressed.<ext>`. */
+  file: File;
+  width: number;
+  height: number;
+  originalWidth: number;
+  originalHeight: number;
+  originalSize: number;
+  compressedSize: number;
+  /** 0–1, e.g. 0.82 means 82% smaller. */
+  reduction: number;
+  source: 'image' | 'raw-preview';
+  /** Embedded JPEG extracted from a RAW file, if any. */
+  preview: Blob | null;
+}
+
+export const DEFAULTS: Readonly<Required<Omit<CompressOptions, 'onProgress'>>>;
+export const RAW_EXTENSIONS: string[];
+export function isRawFile(file: File | Blob): boolean;
+export function compressImage(file: File | Blob, options?: CompressOptions): Promise<CompressResult>;
+/** Stops the background worker and rejects pending jobs. */
+export function terminate(): void;

package/dist/index.js

@@ -0,0 +1,110 @@
+// Public Promise-based API. Talks to worker.js; one image at a time for now.
+
+import { getWorkerUrl } from './worker-url.js';
+
+export const DEFAULTS = Object.freeze({
+  targetQuality: 0.8, // sweet spot: 0.75 if files too big, 0.82 if details look fuzzy
+  maxDimension: 2560,
+  mimeType: 'image/jpeg',
+});
+
+export const RAW_EXTENSIONS = ['.nef', '.nrw', '.dng', '.cr2', '.arw', '.pef'];
+const RAW_PATTERN = new RegExp(`(${RAW_EXTENSIONS.join('|').replace(/\./g, '\\.')})$`, 'i');
+
+export const isRawFile = (file) => RAW_PATTERN.test(file?.name ?? '');
+
+let worker = null;
+let nextId = 0;
+const pending = new Map();
+
+function getWorker() {
+  if (worker) return worker;
+
+  if (typeof OffscreenCanvas === 'undefined' || typeof Worker === 'undefined') {
+    throw new Error('This browser does not support OffscreenCanvas in Web Workers.');
+  }
+
+  worker = new Worker(getWorkerUrl());
+
+  worker.onmessage = ({ data }) => {
+    const job = pending.get(data.id);
+    if (!job) return;
+
+    if (data.type === 'progress') {
+      job.onProgress?.(data.percent, data.stage);
+      return;
+    }
+
+    pending.delete(data.id);
+
+    if (data.type === 'error') {
+      job.reject(new Error(data.message));
+      return;
+    }
+
+    job.onProgress?.(100, 'done');
+    const originalSize = job.file.size;
+    const compressedSize = data.blob.size;
+    job.resolve({
+      blob: data.blob,
+      file: new File([data.blob], renameExtension(job.file.name, job.mimeType), {
+        type: job.mimeType,
+      }),
+      width: data.width,
+      height: data.height,
+      originalWidth: data.originalWidth,
+      originalHeight: data.originalHeight,
+      originalSize,
+      compressedSize,
+      reduction: 1 - compressedSize / originalSize,
+      source: data.preview ? 'raw-preview' : 'image',
+      preview: data.preview ?? null,
+    });
+  };
+
+  worker.onerror = (event) => {
+    for (const job of pending.values()) job.reject(new Error(event.message || 'Worker crashed'));
+    pending.clear();
+    worker.terminate();
+    worker = null;
+  };
+
+  return worker;
+}
+
+function renameExtension(name, mimeType) {
+  const ext = mimeType === 'image/webp' ? 'webp' : 'jpg';
+  return name.replace(/\.[^.]+$/, '') + `-compressed.${ext}`;
+}
+
+/**
+ * @param {File|Blob} file
+ * @param {{ targetQuality?: number, maxDimension?: number, mimeType?: string,
+ *           onProgress?: (percent: number, stage: string) => void }} [options]
+ */
+export function compressImage(file, options = {}) {
+  const isRaw = isRawFile(file);
+  if (!(file instanceof Blob) || (!isRaw && !file.type.startsWith('image/'))) {
+    return Promise.reject(new TypeError('Expected an image or RAW (NEF/DNG/CR2/ARW/PEF) file.'));
+  }
+
+  const { targetQuality, maxDimension, mimeType } = { ...DEFAULTS, ...options };
+
+  return new Promise((resolve, reject) => {
+    const id = ++nextId;
+    pending.set(id, { resolve, reject, file, mimeType, onProgress: options.onProgress });
+    try {
+      getWorker().postMessage({ id, file, maxDimension, quality: targetQuality, mimeType, isRaw });
+    } catch (err) {
+      pending.delete(id);
+      reject(err);
+    }
+  });
+}
+
+export function terminate() {
+  worker?.terminate();
+  worker = null;
+  for (const job of pending.values()) job.reject(new Error('Compressor terminated'));
+  pending.clear();
+}

package/dist/worker-url.js

@@ -0,0 +1,3 @@
+let url;
+export const getWorkerUrl = () =>
+  (url ??= URL.createObjectURL(new Blob(["// Background engine: decode -> resize -> encode, entirely off the main thread.\n\nfunction fitWithin(width, height, maxDimension) {\n  const longest = Math.max(width, height);\n  if (longest <= maxDimension) return { width, height };\n  const scale = maxDimension / longest;\n  return {\n    width: Math.round(width * scale),\n    height: Math.round(height * scale),\n  };\n}\n\nfunction createContext(width, height) {\n  const canvas = new OffscreenCanvas(width, height);\n  const ctx = canvas.getContext('2d', { alpha: true });\n  ctx.imageSmoothingEnabled = true;\n  ctx.imageSmoothingQuality = 'high';\n  return { canvas, ctx };\n}\n\n// Halve repeatedly before the final resize: a single big jump aliases fine\n// patterns (lace, fabric, seeds) into moiré.\nfunction resize(source, targetWidth, targetHeight) {\n  let current = source;\n  let w = source.width;\n  let h = source.height;\n\n  while (w / 2 >= targetWidth && h / 2 >= targetHeight) {\n    w = Math.round(w / 2);\n    h = Math.round(h / 2);\n    const { canvas, ctx } = createContext(w, h);\n    ctx.drawImage(current, 0, 0, w, h);\n    current = canvas;\n  }\n\n  const { canvas, ctx } = createContext(targetWidth, targetHeight);\n  ctx.drawImage(current, 0, 0, targetWidth, targetHeight);\n  return canvas;\n}\n\n// --- RAW support: NEF/DNG/CR2/ARW/PEF are TIFF containers with embedded JPEG previews ---\n\nfunction parseJpegHeader(bytes, start, end) {\n  if (bytes[start] !== 0xff || bytes[start + 1] !== 0xd8) return null;\n  let hasExif = false;\n  let pos = start + 2;\n  while (pos + 9 <= end) {\n    if (bytes[pos] !== 0xff) return null;\n    const marker = bytes[pos + 1];\n    if (marker === 0xff) { pos++; continue; }\n    // SOF0-2 are decodable by browsers; SOF3 etc. are lossless RAW data.\n    if (marker >= 0xc0 && marker <= 0xc2) {\n      return {\n        height: (bytes[pos + 5] << 8) | bytes[pos + 6],\n        width: (bytes[pos + 7] << 8) | bytes[pos + 8],\n        hasExif,\n      };\n    }\n    if ((marker >= 0xc3 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) || marker === 0xda) {\n      return null;\n    }\n    if (marker === 0xe1 && String.fromCharCode(...bytes.subarray(pos + 4, pos + 8)) === 'Exif') hasExif = true;\n    pos += 2 + ((bytes[pos + 2] << 8) | bytes[pos + 3]);\n  }\n  return null;\n}\n\nfunction extractRawPreview(buffer) {\n  const view = new DataView(buffer);\n  const bytes = new Uint8Array(buffer);\n  const size = buffer.byteLength;\n  const order = size >= 8 ? view.getUint16(0) : 0;\n  if (order !== 0x4949 && order !== 0x4d4d) throw new Error('Unsupported RAW format (not TIFF-based).');\n  const le = order === 0x4949;\n  const u16 = (o) => view.getUint16(o, le);\n  const u32 = (o) => view.getUint32(o, le);\n  if (u16(2) !== 42) throw new Error('Unsupported RAW format (not TIFF-based).');\n\n  const readValues = (entry, type, count) => {\n    const width = type === 3 ? 2 : type === 4 || type === 13 ? 4 : 0;\n    if (!width || count > 4096) return [];\n    const base = width * count <= 4 ? entry + 8 : u32(entry + 8);\n    if (base + width * count > size) return [];\n    return Array.from({ length: count }, (_, i) => (width === 2 ? u16(base + i * 2) : u32(base + i * 4)));\n  };\n\n  const candidates = [];\n  const visited = new Set();\n  const queue = [u32(4)];\n  let orientation = 1;\n  let isFirstIfd = true;\n\n  while (queue.length && visited.size < 64) {\n    const ifd = queue.shift();\n    if (!ifd || visited.has(ifd) || ifd + 2 > size) continue;\n    visited.add(ifd);\n\n    const count = u16(ifd);\n    const tags = {};\n    for (let i = 0; i < count; i++) {\n      const entry = ifd + 2 + i * 12;\n      if (entry + 12 > size) break;\n      tags[u16(entry)] = readValues(entry, u16(entry + 2), u32(entry + 4));\n    }\n\n    if (isFirstIfd && tags[0x112]?.[0]) orientation = tags[0x112][0];\n    isFirstIfd = false;\n\n    // JPEGInterchangeFormat / Length (NEF JpgFromRaw, CR2, ARW)\n    if (tags[0x201]?.length && tags[0x202]?.length) {\n      candidates.push({ offset: tags[0x201][0], length: tags[0x202][0] });\n    }\n    // Single-strip JPEG-compressed image (DNG previews)\n    const compression = tags[0x103]?.[0];\n    if ((compression === 6 || compression === 7) && tags[0x111]?.length === 1 && tags[0x117]?.length === 1) {\n      candidates.push({ offset: tags[0x111][0], length: tags[0x117][0] });\n    }\n\n    if (tags[0x14a]) queue.push(...tags[0x14a]);\n    const nextPtr = ifd + 2 + count * 12;\n    if (nextPtr + 4 <= size) queue.push(u32(nextPtr));\n  }\n\n  let best = null;\n  for (const c of candidates) {\n    if (c.offset + c.length > size) continue;\n    const header = parseJpegHeader(bytes, c.offset, c.offset + c.length);\n    if (header && (!best || header.width * header.height > best.width * best.height)) {\n      best = { ...c, ...header };\n    }\n  }\n  if (!best) throw new Error('No decodable JPEG preview found in this RAW file.');\n  return { ...best, orientation: best.hasExif ? 1 : orientation };\n}\n\nfunction applyOrientation(canvas, orientation) {\n  if (!orientation || orientation === 1) return canvas;\n  const w = canvas.width;\n  const h = canvas.height;\n  const swap = orientation >= 5;\n  const { canvas: out, ctx } = createContext(swap ? h : w, swap ? w : h);\n  const transforms = {\n    2: [-1, 0, 0, 1, w, 0],\n    3: [-1, 0, 0, -1, w, h],\n    4: [1, 0, 0, -1, 0, h],\n    5: [0, 1, 1, 0, 0, 0],\n    6: [0, 1, -1, 0, h, 0],\n    7: [0, -1, -1, 0, h, w],\n    8: [0, -1, 1, 0, 0, w],\n  };\n  if (!transforms[orientation]) return canvas;\n  ctx.setTransform(...transforms[orientation]);\n  ctx.drawImage(canvas, 0, 0);\n  return out;\n}\n\nfunction flattenOnWhite(canvas) {\n  const { canvas: out, ctx } = createContext(canvas.width, canvas.height);\n  ctx.fillStyle = '#fff';\n  ctx.fillRect(0, 0, out.width, out.height);\n  ctx.drawImage(canvas, 0, 0);\n  return out;\n}\n\nself.onmessage = async (event) => {\n  const { id, file, maxDimension, quality, mimeType, isRaw } = event.data;\n  const progress = (stage, percent) =>\n    self.postMessage({ id, type: 'progress', stage, percent });\n\n  let bitmap;\n  try {\n    let source = file;\n    let preview = null;\n    let orientation = 1;\n    if (isRaw) {\n      progress('extracting RAW preview', 5);\n      const raw = extractRawPreview(await file.arrayBuffer());\n      preview = file.slice(raw.offset, raw.offset + raw.length, 'image/jpeg');\n      source = preview;\n      orientation = raw.orientation;\n    }\n\n    progress('decoding', 10);\n    bitmap = await createImageBitmap(source, { imageOrientation: 'from-image' });\n\n    progress('resizing', 40);\n    const fitted = fitWithin(bitmap.width, bitmap.height, maxDimension);\n    let canvas = applyOrientation(resize(bitmap, fitted.width, fitted.height), orientation);\n    const { width, height } = canvas;\n    const swapped = orientation >= 5 && orientation <= 8;\n\n    // JPEG has no alpha; transparent pixels would otherwise turn black.\n    if (mimeType === 'image/jpeg') canvas = flattenOnWhite(canvas);\n\n    progress('encoding', 70);\n    const blob = await canvas.convertToBlob({ type: mimeType, quality });\n\n    self.postMessage({\n      id,\n      type: 'done',\n      blob,\n      width,\n      height,\n      originalWidth: swapped ? bitmap.height : bitmap.width,\n      originalHeight: swapped ? bitmap.width : bitmap.height,\n      preview,\n    });\n  } catch (err) {\n    self.postMessage({ id, type: 'error', message: err?.message || String(err) });\n  } finally {\n    bitmap?.close();\n  }\n};\n"], { type: 'text/javascript' })));

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@raghuvamsi_rv/compresspics",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Fast, private, in-browser photo compression with RAW (NEF, DNG, CR2, ARW, PEF) support. Runs in a Web Worker with OffscreenCanvas. Zero dependencies.",
+  "homepage": "https://compresspics.org",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "start": "npm run build && python3 -m http.server 5173 --directory site",
+    "deploy": "npm run build && rsync -avz --delete --exclude .DS_Store site/ \"${DEPLOY_TARGET:?Set DEPLOY_TARGET=user@host:/var/www/compresspics.org}\"",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "image",
+    "compression",
+    "compress",
+    "photo",
+    "jpeg",
+    "webp",
+    "raw",
+    "nef",
+    "dng",
+    "web-worker",
+    "offscreencanvas",
+    "browser"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "fflate": "^0.8.3"
+  }
+}