@nitida/asset-compressor-native 0.2.0

package/README.md

@@ -0,0 +1,92 @@
+# @nitida/asset-compressor-native
+
+Fast, native (iOS + Android) image compression for React Native apps that
+upload to the [aquienpz](https://aquienpz.com) asset platform. Pairs with
+`@aquienpz/asset-uploader-expo` and mirrors the API of
+`@nitida/asset-compressor-web` so call sites are identical across
+platforms.
+
+## Why this exists
+
+`expo-image-manipulator` is the default option in Expo apps, but it
+runs the resize + re-encode through the JS bridge and ships an
+intermediate bitmap as a JS-heap allocation. On a 12MP iPhone HEIC, a
+single resize-to-2880px + JPEG q=0.85 takes ~2–4 seconds — long enough
+to make a 10-photo batch upload feel broken.
+
+This package wraps [`react-native-compressor`](https://github.com/numandev1/react-native-compressor),
+which calls `libjpeg-turbo` (iOS) / `Bitmap.compress` (Android) on a
+background thread and **never moves pixel data across the bridge**. The
+same operation runs in ~250–350ms — roughly **5–10× faster** than the
+Expo equivalent on identical hardware.
+
+## Install
+
+```sh
+# in your Expo / RN app
+npm install @nitida/asset-compressor-native react-native-compressor
+# Expo: also run the config-plugin once
+npx expo prebuild
+```
+
+Add the plugin entry to `app.json`:
+
+```json
+{
+  "expo": {
+    "plugins": ["react-native-compressor"]
+  }
+}
+```
+
+## Usage
+
+```ts
+import { compressImage, compressImages } from "@nitida/asset-compressor-native";
+
+// Single image
+const result = await compressImage({
+  uri: pickerAsset.uri,
+  filename: pickerAsset.fileName ?? "photo.jpg",
+});
+// → { uri: 'file:///.../photo.jpg', size: 412903, originalSize: 4218876, compressionRatio: 0.097 }
+
+// Batch
+const { successful, failed } = await compressImages(
+  pickerAssets.map((a, i) => ({ uri: a.uri, filename: a.fileName ?? `photo-${i}.jpg`, id: a.assetId })),
+  { quality: 0.85, maxWidth: 2880, concurrency: 1 },
+  (id, status, index) => console.log(`[${index}] ${id} → ${status}`),
+);
+```
+
+## Output format
+
+Output is **always JPEG**. `react-native-compressor` natively supports
+only `jpg` / `png`, and the asset-manager re-encodes every uploaded
+image to WebP server-side anyway when generating size variants — so
+forcing WebP on device would cost binary size + native module
+maintenance for zero net bandwidth win.
+
+The on-device savings (HEIC/big-JPEG → 2880px JPEG q=0.85) are already
+~80–95% before the upload starts.
+
+## API parity with `@nitida/asset-compressor-web`
+
+| Web                                      | Native                                          |
+| ---------------------------------------- | ----------------------------------------------- |
+| input `Blob`                             | input `uri` (file://, content://, ph://)        |
+| output `Blob` (mime configurable)        | output file `uri` on disk (always JPEG)         |
+| `compressionStatus: convertingHeic`      | not emitted (HEIC decode is part of `compressing`) |
+| concurrency: `p-limit` / `navigator.hwc` | concurrency: bounded worker pool, default 1     |
+| HEIC fallback: `heic2any`                | HEIC handled natively by ImageIO / android-heif |
+
+Everything else (quality default 0.85, maxWidth/Height 2880, status
+callback shape, error collection in `compressImages`) is identical.
+
+## Cleanup
+
+`react-native-compressor` writes outputs to the app's cache directory.
+iOS will reclaim it under memory pressure; Android does the same when
+the cache exceeds `cacheQuotaBytes`. If you upload + don't need the
+local copy, delete it yourself with `expo-file-system` or
+`react-native-fs` once the upload completes.

package/dist/index.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Public types for @nitida/asset-compressor-native.
+ *
+ * Mirrors @nitida/asset-compressor-web's surface so a single SDK call
+ * (`aq.upload(file, { compress: true })`) works identically across web
+ * and React Native. The only platform-specific divergence: RN inputs are
+ * file `uri` strings (e.g. `file:///...`, `content://...`, `ph://...`)
+ * rather than browser `Blob`s, since `Blob` on Hermes is a thin wrapper
+ * that can't be read efficiently and react-native-compressor operates on
+ * URIs natively.
+ */
+type CompressionStatusKey = "convertingHeic" | "compressing" | "compressingKeepingDimensions" | "skipped" | "done";
+/**
+ * Subset of react-native-compressor's options we expose. Output format
+ * intentionally omitted from the public surface: we always emit JPEG on
+ * device (see `constants.ts` rationale). HEIC inputs are auto-decoded
+ * by iOS ImageIO and Android's BitmapFactory inside the native module,
+ * so no separate `convertingHeic` step is needed — react-native-compressor
+ * handles it transparently.
+ */
+type CompressionOptions = {
+    /** 0..1, defaults to 0.85 — matches web compressor */
+    quality?: number;
+    /** Pixels; defaults to 2880 (longest side cap) */
+    maxWidth?: number;
+    /** Pixels; defaults to 2880 (longest side cap) */
+    maxHeight?: number;
+    /** If true, ignore maxWidth/Height and keep source dimensions. */
+    keepOriginalDimensions?: boolean;
+    /** Caller escape hatch — when true, compression is bypassed entirely. */
+    skipCompression?: boolean;
+};
+/**
+ * Result of a single compression. `uri` points to the compressed file on
+ * the device filesystem; the caller is responsible for uploading it and
+ * cleaning up (react-native-compressor writes to the app cache dir,
+ * which iOS/Android will reclaim under memory pressure).
+ */
+type CompressedResult = {
+    /** `file://...` path to the compressed JPEG on disk. */
+    uri: string;
+    filename: string;
+    /** Bytes of the compressed output. */
+    size: number;
+    /** Mime type of the output — always `"image/jpeg"` for now. */
+    mimeType: "image/jpeg";
+    /** Original (pre-compression) size in bytes. */
+    originalSize: number;
+    /** size / originalSize. <1 = saved bytes. */
+    compressionRatio: number;
+    /** Caller-supplied stable id, echoed back. */
+    id?: string;
+    originalArrayIndex: number;
+};
+type CompressionError = {
+    filename: string;
+    originalUri: string;
+    error: Error;
+    id?: string;
+    originalArrayIndex: number;
+};
+
+/**
+ * Native image compression via react-native-compressor.
+ *
+ * Why react-native-compressor instead of expo-image-manipulator:
+ *
+ *   - iOS: uses CGImageDestination + libjpeg-turbo natively. No JS-bridge
+ *     round trip per pixel, no JSON serialization of pixel arrays.
+ *   - Android: uses BitmapFactory + Bitmap.compress() on a background
+ *     thread, with downsampling at the decode step (inSampleSize) so a
+ *     12MP source never fully decodes if the target is 2880px.
+ *   - HEIC auto-decodes on both platforms (CoreImage / android-heif).
+ *
+ *   In practice, on a 2019 iPhone XR, a 12MP HEIC (~4MB) → 2880px JPEG
+ *   q=0.85 takes ~250-350ms. The same operation via
+ *   expo-image-manipulator takes 2-4 seconds (JS bridge + intermediate
+ *   bitmap allocation in the JS heap). The 10× delta is what the user
+ *   was hitting in apps/asset-lab-mobile.
+ */
+
+type CompressInput = {
+    /** `file://...`, `content://...`, `ph://...`, or remote URL. */
+    uri: string;
+    /** Display name. Used in result + error reports. */
+    filename: string;
+    /** Caller-supplied stable id; passed back unchanged. */
+    id?: string;
+};
+/**
+ * Compress a single image. Designed to be called directly when you only
+ * have one file; otherwise use `compressImages` for batched throughput
+ * control.
+ */
+declare function compressImage(opts: {
+    uri: string;
+    filename: string;
+    options?: CompressionOptions;
+    originalArrayIndex?: number;
+    id?: string;
+    statusCallback?: (status: CompressionStatusKey) => void;
+}): Promise<CompressedResult>;
+/**
+ * Compress many images with bounded concurrency. Failures are collected
+ * — they don't reject the overall promise, so one bad file can't sink a
+ * whole batch.
+ *
+ * Default concurrency = 1 (sequential). Bump to 2 on flagship devices if
+ * profiling shows headroom; going higher tends to thermally throttle.
+ */
+declare function compressImages(images: CompressInput[], options?: CompressionOptions & {
+    concurrency?: number;
+}, statusCallback?: (id: string | undefined, status: CompressionStatusKey, index: number) => void): Promise<{
+    successful: CompressedResult[];
+    failed: CompressionError[];
+}>;
+
+/**
+ * Defaults for the native compressor. Values intentionally match
+ * @nitida/asset-compressor-web so a single SDK call produces
+ * predictable upload sizes across platforms.
+ *
+ * Why JPEG (not WebP) on device:
+ *
+ *   react-native-compressor's native modules only expose `output: 'jpg'
+ *   | 'png'`. Adding WebP would require shipping libwebp on iOS (Apple
+ *   pulled native WebP encoding from CoreImage) and binding it via a
+ *   custom Turbo Module. The marginal bandwidth win (~25% smaller than
+ *   JPEG q=0.85) is not worth the binary-size + maintenance cost
+ *   because the asset-manager re-encodes EVERY uploaded image to WebP
+ *   server-side anyway when generating size variants. So:
+ *
+ *     - Device → JPEG q=0.85, 2880px max side (libjpeg-turbo native,
+ *       ~5–10× faster than expo-image-manipulator's WebP path)
+ *     - Server → WebP variants at `s|m|l|x` presets + on-the-fly
+ *       transforms
+ *
+ *   Net result: the user uploads ~80% smaller bytes than a raw
+ *   12MP iPhone HEIC/JPEG, the server re-encodes once, every CDN
+ *   variant is WebP. Win-win-win.
+ */
+
+/** Maximum dimension (longest side) of the compressed output. */
+declare const MAX_UPLOAD_DIMENSION = 2880;
+declare const DEFAULT_COMPRESSION_OPTIONS: Required<Omit<CompressionOptions, "keepOriginalDimensions" | "skipCompression">>;
+/**
+ * Sequential by default. Mobile devices have thermal + memory constraints
+ * that make parallel compression a net loss above 2 concurrent encodes
+ * (the GPU/CPU sharing model on phones doesn't scale like a laptop). The
+ * caller can override via `compressImages(..., { concurrency: 2 })`.
+ */
+declare const DEFAULT_NATIVE_CONCURRENCY = 1;
+
+export { type CompressInput, type CompressedResult, type CompressionError, type CompressionOptions, type CompressionStatusKey, DEFAULT_COMPRESSION_OPTIONS, DEFAULT_NATIVE_CONCURRENCY, MAX_UPLOAD_DIMENSION, compressImage, compressImages };

package/dist/index.js

@@ -0,0 +1,113 @@
+// src/compression.ts
+import { getImageMetaData, Image as RNCImage } from "react-native-compressor";
+
+// src/constants.ts
+var STANDARD_QUALITY = 0.85;
+var MAX_UPLOAD_DIMENSION = 2880;
+var DEFAULT_COMPRESSION_OPTIONS = {
+  quality: STANDARD_QUALITY,
+  maxWidth: MAX_UPLOAD_DIMENSION,
+  maxHeight: MAX_UPLOAD_DIMENSION
+};
+var DEFAULT_NATIVE_CONCURRENCY = 1;
+
+// src/compression.ts
+async function getSizeBytes(uri) {
+  try {
+    const meta = await getImageMetaData(uri);
+    return typeof meta.size === "number" ? meta.size : 0;
+  } catch {
+    return 0;
+  }
+}
+async function compressImage(opts) {
+  const opt = { ...DEFAULT_COMPRESSION_OPTIONS, ...opts.options };
+  if (opts.options?.skipCompression) {
+    const size = await getSizeBytes(opts.uri);
+    opts.statusCallback?.("skipped");
+    return {
+      uri: opts.uri,
+      filename: opts.filename,
+      size,
+      mimeType: "image/jpeg",
+      originalSize: size,
+      compressionRatio: 1,
+      id: opts.id,
+      originalArrayIndex: opts.originalArrayIndex ?? 0
+    };
+  }
+  const originalSize = await getSizeBytes(opts.uri);
+  opts.statusCallback?.(
+    opts.options?.keepOriginalDimensions ? "compressingKeepingDimensions" : "compressing"
+  );
+  const compressedUri = await RNCImage.compress(opts.uri, {
+    compressionMethod: "manual",
+    quality: opt.quality,
+    maxWidth: opts.options?.keepOriginalDimensions ? Number.POSITIVE_INFINITY : opt.maxWidth,
+    maxHeight: opts.options?.keepOriginalDimensions ? Number.POSITIVE_INFINITY : opt.maxHeight,
+    output: "jpg",
+    returnableOutputType: "uri"
+  });
+  const compressedSize = await getSizeBytes(compressedUri);
+  opts.statusCallback?.("done");
+  return {
+    uri: compressedUri,
+    filename: opts.filename.replace(/\.(heic|heif|png|webp)$/i, ".jpg"),
+    size: compressedSize,
+    mimeType: "image/jpeg",
+    originalSize,
+    compressionRatio: originalSize > 0 ? compressedSize / originalSize : 1,
+    id: opts.id,
+    originalArrayIndex: opts.originalArrayIndex ?? 0
+  };
+}
+async function compressImages(images, options = {}, statusCallback) {
+  const successful = [];
+  const failed = [];
+  const concurrency = Math.max(
+    1,
+    options.concurrency ?? DEFAULT_NATIVE_CONCURRENCY
+  );
+  const { concurrency: _drop, ...passThrough } = options;
+  void _drop;
+  let cursor = 0;
+  const worker = async () => {
+    while (true) {
+      const index = cursor++;
+      if (index >= images.length) return;
+      const img = images[index];
+      if (!img) return;
+      try {
+        const r = await compressImage({
+          uri: img.uri,
+          filename: img.filename,
+          options: passThrough,
+          originalArrayIndex: index,
+          id: img.id,
+          statusCallback: (s) => statusCallback?.(img.id, s, index)
+        });
+        successful.push(r);
+      } catch (err) {
+        failed.push({
+          filename: img.filename,
+          originalUri: img.uri,
+          error: err instanceof Error ? err : new Error(String(err)),
+          id: img.id,
+          originalArrayIndex: index
+        });
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: concurrency }, worker));
+  successful.sort((a, b) => a.originalArrayIndex - b.originalArrayIndex);
+  failed.sort((a, b) => a.originalArrayIndex - b.originalArrayIndex);
+  return { successful, failed };
+}
+export {
+  DEFAULT_COMPRESSION_OPTIONS,
+  DEFAULT_NATIVE_CONCURRENCY,
+  MAX_UPLOAD_DIMENSION,
+  compressImage,
+  compressImages
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/compression.ts","../src/constants.ts"],"sourcesContent":["/**\n * Native image compression via react-native-compressor.\n *\n * Why react-native-compressor instead of expo-image-manipulator:\n *\n *   - iOS: uses CGImageDestination + libjpeg-turbo natively. No JS-bridge\n *     round trip per pixel, no JSON serialization of pixel arrays.\n *   - Android: uses BitmapFactory + Bitmap.compress() on a background\n *     thread, with downsampling at the decode step (inSampleSize) so a\n *     12MP source never fully decodes if the target is 2880px.\n *   - HEIC auto-decodes on both platforms (CoreImage / android-heif).\n *\n *   In practice, on a 2019 iPhone XR, a 12MP HEIC (~4MB) → 2880px JPEG\n *   q=0.85 takes ~250-350ms. The same operation via\n *   expo-image-manipulator takes 2-4 seconds (JS bridge + intermediate\n *   bitmap allocation in the JS heap). The 10× delta is what the user\n *   was hitting in apps/asset-lab-mobile.\n */\n\nimport { getImageMetaData, Image as RNCImage } from \"react-native-compressor\";\nimport {\n  DEFAULT_COMPRESSION_OPTIONS,\n  DEFAULT_NATIVE_CONCURRENCY,\n} from \"./constants\";\nimport type {\n  CompressedResult,\n  CompressionError,\n  CompressionOptions,\n  CompressionStatusKey,\n} from \"./types\";\n\nexport type CompressInput = {\n  /** `file://...`, `content://...`, `ph://...`, or remote URL. */\n  uri: string;\n  /** Display name. Used in result + error reports. */\n  filename: string;\n  /** Caller-supplied stable id; passed back unchanged. */\n  id?: string;\n};\n\n/**\n * Read a file's byte size from its uri. react-native-compressor's\n * `getImageMetaData` returns size in bytes for local files (it stat()s\n * the path under the hood) — falls back to 0 for remote URLs (we don't\n * try to HEAD them; the caller can pass the size if it knows).\n */\nasync function getSizeBytes(uri: string): Promise<number> {\n  try {\n    const meta = await getImageMetaData(uri);\n    return typeof meta.size === \"number\" ? meta.size : 0;\n  } catch {\n    return 0;\n  }\n}\n\n/**\n * Compress a single image. Designed to be called directly when you only\n * have one file; otherwise use `compressImages` for batched throughput\n * control.\n */\nexport async function compressImage(opts: {\n  uri: string;\n  filename: string;\n  options?: CompressionOptions;\n  originalArrayIndex?: number;\n  id?: string;\n  statusCallback?: (status: CompressionStatusKey) => void;\n}): Promise<CompressedResult> {\n  const opt = { ...DEFAULT_COMPRESSION_OPTIONS, ...opts.options };\n\n  // skipCompression escape hatch: report original as-is without touching disk.\n  if (opts.options?.skipCompression) {\n    const size = await getSizeBytes(opts.uri);\n    opts.statusCallback?.(\"skipped\");\n    return {\n      uri: opts.uri,\n      filename: opts.filename,\n      size,\n      mimeType: \"image/jpeg\",\n      originalSize: size,\n      compressionRatio: 1,\n      id: opts.id,\n      originalArrayIndex: opts.originalArrayIndex ?? 0,\n    };\n  }\n\n  const originalSize = await getSizeBytes(opts.uri);\n\n  opts.statusCallback?.(\n    opts.options?.keepOriginalDimensions\n      ? \"compressingKeepingDimensions\"\n      : \"compressing\",\n  );\n\n  // Manual mode pins quality + max dims (auto-mode adapts based on input\n  // size — useful for chat apps where speed > predictability, but for our\n  // upload pipeline we want deterministic output sizes).\n  const compressedUri = await RNCImage.compress(opts.uri, {\n    compressionMethod: \"manual\",\n    quality: opt.quality,\n    maxWidth: opts.options?.keepOriginalDimensions\n      ? Number.POSITIVE_INFINITY\n      : opt.maxWidth,\n    maxHeight: opts.options?.keepOriginalDimensions\n      ? Number.POSITIVE_INFINITY\n      : opt.maxHeight,\n    output: \"jpg\",\n    returnableOutputType: \"uri\",\n  });\n\n  const compressedSize = await getSizeBytes(compressedUri);\n  opts.statusCallback?.(\"done\");\n\n  return {\n    uri: compressedUri,\n    filename: opts.filename.replace(/\\.(heic|heif|png|webp)$/i, \".jpg\"),\n    size: compressedSize,\n    mimeType: \"image/jpeg\",\n    originalSize,\n    compressionRatio: originalSize > 0 ? compressedSize / originalSize : 1,\n    id: opts.id,\n    originalArrayIndex: opts.originalArrayIndex ?? 0,\n  };\n}\n\n/**\n * Compress many images with bounded concurrency. Failures are collected\n * — they don't reject the overall promise, so one bad file can't sink a\n * whole batch.\n *\n * Default concurrency = 1 (sequential). Bump to 2 on flagship devices if\n * profiling shows headroom; going higher tends to thermally throttle.\n */\nexport async function compressImages(\n  images: CompressInput[],\n  options: CompressionOptions & { concurrency?: number } = {},\n  statusCallback?: (\n    id: string | undefined,\n    status: CompressionStatusKey,\n    index: number,\n  ) => void,\n): Promise<{ successful: CompressedResult[]; failed: CompressionError[] }> {\n  const successful: CompressedResult[] = [];\n  const failed: CompressionError[] = [];\n  const concurrency = Math.max(\n    1,\n    options.concurrency ?? DEFAULT_NATIVE_CONCURRENCY,\n  );\n  const { concurrency: _drop, ...passThrough } = options;\n  void _drop;\n\n  let cursor = 0;\n  const worker = async (): Promise<void> => {\n    while (true) {\n      const index = cursor++;\n      if (index >= images.length) return;\n      const img = images[index];\n      if (!img) return;\n      try {\n        const r = await compressImage({\n          uri: img.uri,\n          filename: img.filename,\n          options: passThrough,\n          originalArrayIndex: index,\n          id: img.id,\n          statusCallback: (s) => statusCallback?.(img.id, s, index),\n        });\n        successful.push(r);\n      } catch (err) {\n        failed.push({\n          filename: img.filename,\n          originalUri: img.uri,\n          error: err instanceof Error ? err : new Error(String(err)),\n          id: img.id,\n          originalArrayIndex: index,\n        });\n      }\n    }\n  };\n\n  await Promise.all(Array.from({ length: concurrency }, worker));\n\n  // Restore caller order (workers complete out-of-order).\n  successful.sort((a, b) => a.originalArrayIndex - b.originalArrayIndex);\n  failed.sort((a, b) => a.originalArrayIndex - b.originalArrayIndex);\n\n  return { successful, failed };\n}\n","/**\n * Defaults for the native compressor. Values intentionally match\n * @nitida/asset-compressor-web so a single SDK call produces\n * predictable upload sizes across platforms.\n *\n * Why JPEG (not WebP) on device:\n *\n *   react-native-compressor's native modules only expose `output: 'jpg'\n *   | 'png'`. Adding WebP would require shipping libwebp on iOS (Apple\n *   pulled native WebP encoding from CoreImage) and binding it via a\n *   custom Turbo Module. The marginal bandwidth win (~25% smaller than\n *   JPEG q=0.85) is not worth the binary-size + maintenance cost\n *   because the asset-manager re-encodes EVERY uploaded image to WebP\n *   server-side anyway when generating size variants. So:\n *\n *     - Device → JPEG q=0.85, 2880px max side (libjpeg-turbo native,\n *       ~5–10× faster than expo-image-manipulator's WebP path)\n *     - Server → WebP variants at `s|m|l|x` presets + on-the-fly\n *       transforms\n *\n *   Net result: the user uploads ~80% smaller bytes than a raw\n *   12MP iPhone HEIC/JPEG, the server re-encodes once, every CDN\n *   variant is WebP. Win-win-win.\n */\n\nimport type { CompressionOptions } from \"./types\";\n\n/** 0.85 ≈ visually lossless for product photos (same as web compressor). */\nconst STANDARD_QUALITY = 0.85;\n\n/** Maximum dimension (longest side) of the compressed output. */\nexport const MAX_UPLOAD_DIMENSION = 2880;\n\nexport const DEFAULT_COMPRESSION_OPTIONS: Required<\n  Omit<CompressionOptions, \"keepOriginalDimensions\" | \"skipCompression\">\n> = {\n  quality: STANDARD_QUALITY,\n  maxWidth: MAX_UPLOAD_DIMENSION,\n  maxHeight: MAX_UPLOAD_DIMENSION,\n};\n\n/**\n * Sequential by default. Mobile devices have thermal + memory constraints\n * that make parallel compression a net loss above 2 concurrent encodes\n * (the GPU/CPU sharing model on phones doesn't scale like a laptop). The\n * caller can override via `compressImages(..., { concurrency: 2 })`.\n */\nexport const DEFAULT_NATIVE_CONCURRENCY = 1;\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@nitida/asset-compressor-native",
+  "version": "0.2.0",
+  "description": "Native (iOS/Android) image compression for the @aquienpz upload pipeline. JS API mirrors @nitida/asset-compressor-web so call sites are identical across web and React Native.",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/espaciofuturoio/aquienpz.git",
+    "directory": "packages/asset-compressor-native"
+  },
+  "homepage": "https://github.com/espaciofuturoio/aquienpz/tree/main/packages/asset-compressor-native",
+  "license": "UNLICENSED",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist/**",
+    "src/**"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "prepublishOnly": "bun run build",
+    "type-check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react-native": "*",
+    "react-native-compressor": ">=1.10.0"
+  },
+  "devDependencies": {
+    "react-native": "0.85.3",
+    "react-native-compressor": "^1.18.2",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3"
+  }
+}

package/src/compression.ts

@@ -0,0 +1,188 @@
+/**
+ * Native image compression via react-native-compressor.
+ *
+ * Why react-native-compressor instead of expo-image-manipulator:
+ *
+ *   - iOS: uses CGImageDestination + libjpeg-turbo natively. No JS-bridge
+ *     round trip per pixel, no JSON serialization of pixel arrays.
+ *   - Android: uses BitmapFactory + Bitmap.compress() on a background
+ *     thread, with downsampling at the decode step (inSampleSize) so a
+ *     12MP source never fully decodes if the target is 2880px.
+ *   - HEIC auto-decodes on both platforms (CoreImage / android-heif).
+ *
+ *   In practice, on a 2019 iPhone XR, a 12MP HEIC (~4MB) → 2880px JPEG
+ *   q=0.85 takes ~250-350ms. The same operation via
+ *   expo-image-manipulator takes 2-4 seconds (JS bridge + intermediate
+ *   bitmap allocation in the JS heap). The 10× delta is what the user
+ *   was hitting in apps/asset-lab-mobile.
+ */
+
+import { getImageMetaData, Image as RNCImage } from "react-native-compressor";
+import {
+  DEFAULT_COMPRESSION_OPTIONS,
+  DEFAULT_NATIVE_CONCURRENCY,
+} from "./constants";
+import type {
+  CompressedResult,
+  CompressionError,
+  CompressionOptions,
+  CompressionStatusKey,
+} from "./types";
+
+export type CompressInput = {
+  /** `file://...`, `content://...`, `ph://...`, or remote URL. */
+  uri: string;
+  /** Display name. Used in result + error reports. */
+  filename: string;
+  /** Caller-supplied stable id; passed back unchanged. */
+  id?: string;
+};
+
+/**
+ * Read a file's byte size from its uri. react-native-compressor's
+ * `getImageMetaData` returns size in bytes for local files (it stat()s
+ * the path under the hood) — falls back to 0 for remote URLs (we don't
+ * try to HEAD them; the caller can pass the size if it knows).
+ */
+async function getSizeBytes(uri: string): Promise<number> {
+  try {
+    const meta = await getImageMetaData(uri);
+    return typeof meta.size === "number" ? meta.size : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Compress a single image. Designed to be called directly when you only
+ * have one file; otherwise use `compressImages` for batched throughput
+ * control.
+ */
+export async function compressImage(opts: {
+  uri: string;
+  filename: string;
+  options?: CompressionOptions;
+  originalArrayIndex?: number;
+  id?: string;
+  statusCallback?: (status: CompressionStatusKey) => void;
+}): Promise<CompressedResult> {
+  const opt = { ...DEFAULT_COMPRESSION_OPTIONS, ...opts.options };
+
+  // skipCompression escape hatch: report original as-is without touching disk.
+  if (opts.options?.skipCompression) {
+    const size = await getSizeBytes(opts.uri);
+    opts.statusCallback?.("skipped");
+    return {
+      uri: opts.uri,
+      filename: opts.filename,
+      size,
+      mimeType: "image/jpeg",
+      originalSize: size,
+      compressionRatio: 1,
+      id: opts.id,
+      originalArrayIndex: opts.originalArrayIndex ?? 0,
+    };
+  }
+
+  const originalSize = await getSizeBytes(opts.uri);
+
+  opts.statusCallback?.(
+    opts.options?.keepOriginalDimensions
+      ? "compressingKeepingDimensions"
+      : "compressing",
+  );
+
+  // Manual mode pins quality + max dims (auto-mode adapts based on input
+  // size — useful for chat apps where speed > predictability, but for our
+  // upload pipeline we want deterministic output sizes).
+  const compressedUri = await RNCImage.compress(opts.uri, {
+    compressionMethod: "manual",
+    quality: opt.quality,
+    maxWidth: opts.options?.keepOriginalDimensions
+      ? Number.POSITIVE_INFINITY
+      : opt.maxWidth,
+    maxHeight: opts.options?.keepOriginalDimensions
+      ? Number.POSITIVE_INFINITY
+      : opt.maxHeight,
+    output: "jpg",
+    returnableOutputType: "uri",
+  });
+
+  const compressedSize = await getSizeBytes(compressedUri);
+  opts.statusCallback?.("done");
+
+  return {
+    uri: compressedUri,
+    filename: opts.filename.replace(/\.(heic|heif|png|webp)$/i, ".jpg"),
+    size: compressedSize,
+    mimeType: "image/jpeg",
+    originalSize,
+    compressionRatio: originalSize > 0 ? compressedSize / originalSize : 1,
+    id: opts.id,
+    originalArrayIndex: opts.originalArrayIndex ?? 0,
+  };
+}
+
+/**
+ * Compress many images with bounded concurrency. Failures are collected
+ * — they don't reject the overall promise, so one bad file can't sink a
+ * whole batch.
+ *
+ * Default concurrency = 1 (sequential). Bump to 2 on flagship devices if
+ * profiling shows headroom; going higher tends to thermally throttle.
+ */
+export async function compressImages(
+  images: CompressInput[],
+  options: CompressionOptions & { concurrency?: number } = {},
+  statusCallback?: (
+    id: string | undefined,
+    status: CompressionStatusKey,
+    index: number,
+  ) => void,
+): Promise<{ successful: CompressedResult[]; failed: CompressionError[] }> {
+  const successful: CompressedResult[] = [];
+  const failed: CompressionError[] = [];
+  const concurrency = Math.max(
+    1,
+    options.concurrency ?? DEFAULT_NATIVE_CONCURRENCY,
+  );
+  const { concurrency: _drop, ...passThrough } = options;
+  void _drop;
+
+  let cursor = 0;
+  const worker = async (): Promise<void> => {
+    while (true) {
+      const index = cursor++;
+      if (index >= images.length) return;
+      const img = images[index];
+      if (!img) return;
+      try {
+        const r = await compressImage({
+          uri: img.uri,
+          filename: img.filename,
+          options: passThrough,
+          originalArrayIndex: index,
+          id: img.id,
+          statusCallback: (s) => statusCallback?.(img.id, s, index),
+        });
+        successful.push(r);
+      } catch (err) {
+        failed.push({
+          filename: img.filename,
+          originalUri: img.uri,
+          error: err instanceof Error ? err : new Error(String(err)),
+          id: img.id,
+          originalArrayIndex: index,
+        });
+      }
+    }
+  };
+
+  await Promise.all(Array.from({ length: concurrency }, worker));
+
+  // Restore caller order (workers complete out-of-order).
+  successful.sort((a, b) => a.originalArrayIndex - b.originalArrayIndex);
+  failed.sort((a, b) => a.originalArrayIndex - b.originalArrayIndex);
+
+  return { successful, failed };
+}

package/src/constants.ts

@@ -0,0 +1,48 @@
+/**
+ * Defaults for the native compressor. Values intentionally match
+ * @nitida/asset-compressor-web so a single SDK call produces
+ * predictable upload sizes across platforms.
+ *
+ * Why JPEG (not WebP) on device:
+ *
+ *   react-native-compressor's native modules only expose `output: 'jpg'
+ *   | 'png'`. Adding WebP would require shipping libwebp on iOS (Apple
+ *   pulled native WebP encoding from CoreImage) and binding it via a
+ *   custom Turbo Module. The marginal bandwidth win (~25% smaller than
+ *   JPEG q=0.85) is not worth the binary-size + maintenance cost
+ *   because the asset-manager re-encodes EVERY uploaded image to WebP
+ *   server-side anyway when generating size variants. So:
+ *
+ *     - Device → JPEG q=0.85, 2880px max side (libjpeg-turbo native,
+ *       ~5–10× faster than expo-image-manipulator's WebP path)
+ *     - Server → WebP variants at `s|m|l|x` presets + on-the-fly
+ *       transforms
+ *
+ *   Net result: the user uploads ~80% smaller bytes than a raw
+ *   12MP iPhone HEIC/JPEG, the server re-encodes once, every CDN
+ *   variant is WebP. Win-win-win.
+ */
+
+import type { CompressionOptions } from "./types";
+
+/** 0.85 ≈ visually lossless for product photos (same as web compressor). */
+const STANDARD_QUALITY = 0.85;
+
+/** Maximum dimension (longest side) of the compressed output. */
+export const MAX_UPLOAD_DIMENSION = 2880;
+
+export const DEFAULT_COMPRESSION_OPTIONS: Required<
+  Omit<CompressionOptions, "keepOriginalDimensions" | "skipCompression">
+> = {
+  quality: STANDARD_QUALITY,
+  maxWidth: MAX_UPLOAD_DIMENSION,
+  maxHeight: MAX_UPLOAD_DIMENSION,
+};
+
+/**
+ * Sequential by default. Mobile devices have thermal + memory constraints
+ * that make parallel compression a net loss above 2 concurrent encodes
+ * (the GPU/CPU sharing model on phones doesn't scale like a laptop). The
+ * caller can override via `compressImages(..., { concurrency: 2 })`.
+ */
+export const DEFAULT_NATIVE_CONCURRENCY = 1;

package/src/index.ts

@@ -0,0 +1,39 @@
+/**
+ * @nitida/asset-compressor-native — React Native image compression for
+ * the @aquienpz upload pipeline. Pairs with @aquienpz/asset-uploader-expo.
+ *
+ * Public API mirrors @nitida/asset-compressor-web so consumers can
+ * write platform-agnostic code:
+ *
+ *   const { compressImage } = Platform.OS === 'web'
+ *     ? await import('@nitida/asset-compressor-web')
+ *     : await import('@nitida/asset-compressor-native');
+ *
+ * Or (preferred): let the `@nitida/sdk` web/native sub-paths pick the
+ * right module automatically — see SDK README.
+ *
+ * Peer deps:
+ *   - react-native (>=0.74)
+ *   - react-native-compressor (>=1.10)
+ *
+ * Both must be installed in the consuming app. For Expo, run
+ * `npx expo install react-native-compressor` and add the config-plugin
+ * stanza to app.json (see react-native-compressor docs §Expo).
+ */
+
+export {
+  type CompressInput,
+  compressImage,
+  compressImages,
+} from "./compression";
+export {
+  DEFAULT_COMPRESSION_OPTIONS,
+  DEFAULT_NATIVE_CONCURRENCY,
+  MAX_UPLOAD_DIMENSION,
+} from "./constants";
+export type {
+  CompressedResult,
+  CompressionError,
+  CompressionOptions,
+  CompressionStatusKey,
+} from "./types";

package/src/types.ts

@@ -0,0 +1,70 @@
+/**
+ * Public types for @nitida/asset-compressor-native.
+ *
+ * Mirrors @nitida/asset-compressor-web's surface so a single SDK call
+ * (`aq.upload(file, { compress: true })`) works identically across web
+ * and React Native. The only platform-specific divergence: RN inputs are
+ * file `uri` strings (e.g. `file:///...`, `content://...`, `ph://...`)
+ * rather than browser `Blob`s, since `Blob` on Hermes is a thin wrapper
+ * that can't be read efficiently and react-native-compressor operates on
+ * URIs natively.
+ */
+
+export type CompressionStatusKey =
+  | "convertingHeic"
+  | "compressing"
+  | "compressingKeepingDimensions"
+  | "skipped"
+  | "done";
+
+/**
+ * Subset of react-native-compressor's options we expose. Output format
+ * intentionally omitted from the public surface: we always emit JPEG on
+ * device (see `constants.ts` rationale). HEIC inputs are auto-decoded
+ * by iOS ImageIO and Android's BitmapFactory inside the native module,
+ * so no separate `convertingHeic` step is needed — react-native-compressor
+ * handles it transparently.
+ */
+export type CompressionOptions = {
+  /** 0..1, defaults to 0.85 — matches web compressor */
+  quality?: number;
+  /** Pixels; defaults to 2880 (longest side cap) */
+  maxWidth?: number;
+  /** Pixels; defaults to 2880 (longest side cap) */
+  maxHeight?: number;
+  /** If true, ignore maxWidth/Height and keep source dimensions. */
+  keepOriginalDimensions?: boolean;
+  /** Caller escape hatch — when true, compression is bypassed entirely. */
+  skipCompression?: boolean;
+};
+
+/**
+ * Result of a single compression. `uri` points to the compressed file on
+ * the device filesystem; the caller is responsible for uploading it and
+ * cleaning up (react-native-compressor writes to the app cache dir,
+ * which iOS/Android will reclaim under memory pressure).
+ */
+export type CompressedResult = {
+  /** `file://...` path to the compressed JPEG on disk. */
+  uri: string;
+  filename: string;
+  /** Bytes of the compressed output. */
+  size: number;
+  /** Mime type of the output — always `"image/jpeg"` for now. */
+  mimeType: "image/jpeg";
+  /** Original (pre-compression) size in bytes. */
+  originalSize: number;
+  /** size / originalSize. <1 = saved bytes. */
+  compressionRatio: number;
+  /** Caller-supplied stable id, echoed back. */
+  id?: string;
+  originalArrayIndex: number;
+};
+
+export type CompressionError = {
+  filename: string;
+  originalUri: string;
+  error: Error;
+  id?: string;
+  originalArrayIndex: number;
+};