@skyprint/image2pdf-expo 0.1.0

package/README.md

@@ -0,0 +1,136 @@
+# @skyprint/image2pdf-expo
+
+React Native / Expo bridge for the
+[`image2pdf`](https://git.duguying.net/cloudprinter/image2pdf) WebAssembly
+library. Converts JPG / PNG / (pre-converted) HEIC images into a single
+A4 PDF entirely on-device, with no network calls and no cloud round-trip.
+
+This package exists because **Hermes** (the JS engine bundled in Expo
+Go) does not implement `WebAssembly`. The wasm is therefore loaded
+inside a hidden `react-native-webview`, which runs the full browser
+kernel (iOS WebKit / Android Blink) and *does* support wasm. We talk to
+the WebView via `postMessage` and treat the wasm as a black box.
+
+## Install
+
+```sh
+# in your Expo / RN app
+npm install @skyprint/image2pdf-expo
+# + the peer dependencies (see package.json):
+#   expo, expo-asset, expo-file-system, react-native-webview
+```
+
+## Use
+
+```tsx
+import { useImage2Pdf, Image2PdfBridge } from '@skyprint/image2pdf-expo';
+
+function MyScreen() {
+  const { convert, status, result, error } = useImage2Pdf();
+
+  return (
+    <>
+      {/* Mount the bridge once near the top of your tree.
+          It renders as a 0×0 absolutely-positioned WebView. */}
+      <Image2PdfBridge />
+
+      <Button
+        title="Convert"
+        onPress={() => convert(imageUris, { title: 'my-doc', marginMm: 5 })}
+      />
+
+      <Text>status: {status}</Text>
+      {result && <Text>PDF: {result.pages} pages, {result.bytes} bytes, {result.durationMs} ms</Text>}
+      {error && <Text>error: {String(error)}</Text>}
+    </>
+  );
+}
+```
+
+`convert()` takes a list of `file://` URIs (the same shape
+`expo-image-picker` returns) and returns:
+
+```ts
+interface ConvertResult {
+  uri: string;       // local file:// URI of the saved PDF (in cache dir)
+  bytes: number;     // PDF size in bytes
+  pages: number;     // page count
+  durationMs: number; // wall time spent in the wasm convert() call
+}
+```
+
+## How the bridge works
+
+```
+┌──────────────────────┐        ┌─────────────────────────────┐
+│   React Native side  │  post  │   Hidden WebView            │
+│  (useImage2Pdf hook) │ ─────► │  bridge.js glue             │
+│                      │ ◄───── │    └─ image2pdf.js (wasm)   │
+└──────────────────────┘        │        └─ image2pdf_bg.wasm │
+                                └─────────────────────────────┘
+```
+
+For 30 × 8 MB HEIC photos, the wasm call itself takes < 1 s; the
+WebView's data-URL fetch of the local files is essentially a memcpy.
+
+## Options
+
+| Field      | Default        | Description                                |
+| ---------- | -------------- | ------------------------------------------ |
+| `title`    | `"image2pdf"`  | PDF document title                         |
+| `author`   | `""`           | PDF author metadata                        |
+| `marginMm` | `10`           | Page margin in millimeters                 |
+| `dpi`      | `75`           | Pixels-per-inch for image → point scaling  |
+
+## HEIC support
+
+iOS camera photos are HEIC by default. Our wasm does **not** decode HEIC
+on React Native (it would require C++ stdlib in the bundle). The
+recommended workaround:
+
+```tsx
+import * as ImageManipulator from 'expo-image-manipulator';
+
+const jpegUri = await ImageManipulator.manipulateAsync(
+  heicUri,
+  [],
+  { compress: 1, format: ImageManipulator.SaveFormat.JPEG },
+).then((r) => r.uri);
+```
+
+`expo-image-manipulator` uses iOS ImageIO / Android MediaCodec, so the
+HEIC decode never enters our wasm. Functionally equivalent to native
+HEIC support, with a small CPU cost (the re-encode is fast on modern
+phones and the resulting JPEG is smaller than HEIC anyway).
+
+## Example app (SDK 55)
+
+```sh
+# from repo root — stage wasm into assets/
+make expo-build
+
+cd example
+npm install
+npx expo start --clear
+```
+
+The example depends on this package via `"file:.."`. Metro needs
+[`example/metro.config.js`](example/metro.config.js) to watch the parent
+directory. **Do not run `npm install` in `integrations/expo/`** (the
+library root) — that creates a second `node_modules` with its own
+`react-native` and breaks the example bundler.
+
+## Build / publish
+
+```sh
+# from the image2pdf repo root, after editing the rust lib:
+make expo-build       # rebuilds wasm, copies into this package's assets/
+
+# then in this directory:
+npm version patch
+npm publish
+```
+
+## License
+
+MIT — see the parent repo's [LICENSE](../../LICENSE).

package/assets/README.md

@@ -0,0 +1,29 @@
+# image2pdf
+
+Convert JPG, PNG, and HEIC images to a single A4 PDF — entirely in WebAssembly,
+running in the browser, Node.js, a bundler, or **React Native (Expo Go) via a
+WebView bridge**.
+
+Status: 🚧 early development. See [`/root/.claude/plans/webassembly-rust-jpg-png-heic-pdf-witty-wreath.md`](/root/.claude/plans/webassembly-rust-jpg-png-heic-pdf-witty-wreath.md) for the implementation plan.
+
+## Build
+
+```sh
+# install prerequisites once (Linux example)
+rustup target add wasm32-unknown-unknown
+curl https://rustwasm.github.io/wasm-pack/installer/init.sh | sh
+
+# build the three wasm-pack targets
+./scripts/build-wasm.sh
+```
+
+## Use
+
+Detailed usage docs land alongside Step 6 (Expo integration). For now see the
+plan file for the API surface and the architecture diagram.
+
+## License
+
+MIT. See [LICENSE](./LICENSE). Third-party dependencies are listed in
+[THIRD_PARTY_LICENSES.md](../../THIRD_PARTY_LICENSES.md) (includes the optional
+`heic` crate — AGPL-3.0-only or Imazen commercial).

package/assets/bridge.bundle

@@ -0,0 +1,253 @@
+// WebView-side glue for image2pdf.
+//
+// Shipped as `bridge.bundle` (Metro asset) and staged as `bridge.js` beside
+// bridge.html so ES module relative imports resolve. Extension `.bundle` avoids
+// Metro treating `*.web.js` as a `web` platform source file (ext `js`).
+
+const statusEl = document.getElementById('status');
+const logEl = document.getElementById('log');
+
+const RN_BRIDGE = window.ReactNativeWebView;
+const post = (msg) => RN_BRIDGE && RN_BRIDGE.postMessage(JSON.stringify(msg));
+
+function log(msg, data) {
+  const line = data !== undefined ? `${msg} ${JSON.stringify(data)}` : msg;
+  const stamped = `${new Date().toISOString()} ${line}`;
+  if (logEl) logEl.textContent += stamped + '\n';
+  if (typeof console !== 'undefined') console.log('[image2pdf:bridge]', stamped);
+  try {
+    post({ type: 'log', message: line });
+  } catch {
+    /* post() not ready yet */
+  }
+}
+
+/** @type {((images: Uint8Array[], options: object) => Uint8Array) | null} */
+let convertFn = null;
+
+/** id → Uint8Array. Kept in-memory until `finalize` (or `reset`) is called. */
+const images = new Map();
+
+/** id → in-flight chunked base64 from RN */
+const pendingAdds = new Map();
+
+/** Idempotent, sequential, single-shot. */
+let busy = false;
+
+/** @type {{ onChunk: (msg: object) => void; onErr: (msg: object) => void } | null} */
+let wasmWaiter = null;
+
+function base64ToArrayBuffer(b64) {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes.buffer;
+}
+
+function base64ToUint8Array(b64) {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+function requestWasmBytes() {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let total = null;
+    const timeout = setTimeout(() => {
+      wasmWaiter = null;
+      reject(new Error('wasm bytes timeout'));
+    }, 120_000);
+
+    wasmWaiter = {
+      onChunk(msg) {
+        if (total === null) total = msg.total;
+        chunks[msg.index] = msg.data;
+        if (chunks.length === total && chunks.every((c) => c != null)) {
+          clearTimeout(timeout);
+          wasmWaiter = null;
+          try {
+            resolve(base64ToArrayBuffer(chunks.join('')));
+          } catch (e) {
+            reject(e);
+          }
+        }
+      },
+      onErr(msg) {
+        clearTimeout(timeout);
+        wasmWaiter = null;
+        reject(new Error(msg.message || 'wasm delivery failed'));
+      },
+    };
+    post({ type: 'needWasm' });
+  });
+}
+
+(async () => {
+  try {
+    log('wasm init start');
+    const mod = await import('./image2pdf.js');
+    log('requesting wasm from RN');
+    const wasmBytes = await requestWasmBytes();
+    log('wasm bytes loaded', { bytes: wasmBytes.byteLength });
+    await mod.default(wasmBytes);
+    convertFn = mod.convert;
+    statusEl.textContent = 'ready';
+    log('wasm init ok');
+    post({ type: 'ready' });
+  } catch (e) {
+    const message = e?.message || String(e);
+    statusEl.textContent = 'wasm load failed: ' + message;
+    log('wasm init failed', { message, stack: e?.stack || String(e) });
+    post({ type: 'error', requestId: '__wasm__', message: 'wasm init failed: ' + message });
+  }
+})();
+
+function onRnMessage(ev) {
+  let msg;
+  try {
+    msg = JSON.parse(ev.data);
+  } catch {
+    log('ignoring non-JSON message: ' + ev.data);
+    return;
+  }
+  if (wasmWaiter) {
+    if (msg.type === 'wasmChunk') {
+      wasmWaiter.onChunk(msg);
+      return;
+    }
+    if (msg.type === 'wasmErr') {
+      wasmWaiter.onErr(msg);
+      return;
+    }
+  }
+  void handle(msg);
+}
+
+window.addEventListener('message', onRnMessage);
+document.addEventListener('message', onRnMessage);
+
+async function handle(msg) {
+  log('handle', { type: msg.type, images: images.size, busy });
+  switch (msg.type) {
+    case 'init':
+      break;
+
+    case 'addBytes': {
+      if (busy) {
+        post({ type: 'addErr', id: msg.id, message: 'busy' });
+        return;
+      }
+      let pending = pendingAdds.get(msg.id);
+      if (!pending) {
+        pending = { chunks: [], total: msg.total };
+        pendingAdds.set(msg.id, pending);
+        log('addBytes start', { id: msg.id, total: msg.total });
+      }
+      pending.chunks[msg.index] = msg.data;
+      if (pending.chunks.length !== msg.total || !pending.chunks.every((c) => c != null)) {
+        return;
+      }
+      pendingAdds.delete(msg.id);
+      try {
+        const bytes = base64ToUint8Array(pending.chunks.join(''));
+        images.set(msg.id, bytes);
+        log('add ok', { id: msg.id, bytes: bytes.length, total: images.size });
+        post({ type: 'addOk', id: msg.id });
+      } catch (e) {
+        log('add decode failed', { id: msg.id, message: String(e.message || e) });
+        post({ type: 'addErr', id: msg.id, message: String(e.message || e) });
+      }
+      break;
+    }
+
+    case 'finalize': {
+      if (busy) {
+        post({ type: 'error', requestId: msg.requestId, message: 'busy' });
+        return;
+      }
+      if (!convertFn) {
+        post({
+          type: 'error',
+          requestId: msg.requestId,
+          message: 'wasm not initialized',
+        });
+        return;
+      }
+      if (images.size === 0) {
+        log('finalize rejected: no images in map');
+        post({
+          type: 'error',
+          requestId: msg.requestId,
+          message: 'no images added',
+        });
+        return;
+      }
+      busy = true;
+      statusEl.textContent = 'converting…';
+      log('finalize start', { requestId: msg.requestId, images: images.size });
+      try {
+        const arr = Array.from(images.values());
+        const opts = {
+          title: msg.options?.title || 'image2pdf',
+          author: msg.options?.author || '',
+          marginMm: msg.options?.marginMm ?? 10,
+          dpi: msg.options?.dpi ?? 75,
+        };
+        const t0 = performance.now();
+        log('wasm convert() start', { pages: arr.length, opts });
+        const pdf = convertFn(arr, opts);
+        const dt = performance.now() - t0;
+        log('wasm convert() ok', { bytes: pdf.length, ms: dt.toFixed(1) });
+
+        const b64t0 = performance.now();
+        const b64 = bytesToBase64(pdf);
+        log('base64 encode ok', { b64Len: b64.length, ms: (performance.now() - b64t0).toFixed(1) });
+        log('posting done to RN');
+        post({
+          type: 'done',
+          requestId: msg.requestId,
+          pdfBase64: b64,
+          pages: arr.length,
+          bytes: pdf.length,
+        });
+        statusEl.textContent = 'done';
+      } catch (e) {
+        log('finalize error', { message: e.message || String(e), stack: e.stack });
+        post({
+          type: 'error',
+          requestId: msg.requestId,
+          message: String(e.message || e),
+        });
+        statusEl.textContent = 'error: ' + (e.message || e);
+      } finally {
+        busy = false;
+      }
+      break;
+    }
+
+    case 'reset': {
+      const n = images.size;
+      images.clear();
+      pendingAdds.clear();
+      log('  reset (cleared ' + n + ' images)');
+      break;
+    }
+
+    default:
+      log('unknown message type: ' + msg.type);
+  }
+}
+
+function bytesToBase64(bytes) {
+  let binary = '';
+  const chunk = 0x8000;
+  for (let i = 0; i < bytes.length; i += chunk) {
+    binary += String.fromCharCode.apply(
+      null,
+      bytes.subarray(i, Math.min(i + chunk, bytes.length)),
+    );
+  }
+  return btoa(binary);
+}

package/assets/bridge.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>image2pdf bridge</title>
+  <style>
+    body { font-family: monospace; padding: 1rem; color: #1a1a1a; }
+    pre { background: #f3f4f6; padding: 0.5rem; border-radius: 6px; }
+    #status { font-weight: bold; }
+  </style>
+</head>
+<body>
+  <h1>image2pdf bridge</h1>
+  <div id="status">loading wasm…</div>
+  <pre id="log"></pre>
+  <script type="module" src="./bridge.js"></script>
+</body>
+</html>