rosetta-squint 1.0.0

package/README.md

@@ -0,0 +1,97 @@
+# rosetta-squint — JS/TS
+
+Point at a file path or pass raw image bytes; get back the perceptual hash hex string that every other `rosetta-squint` port produces for the same input.
+
+## Install (Node)
+
+```bash
+npm install rosetta-squint
+```
+
+```ts
+import { phash, phashBytes } from "rosetta-squint";
+
+const h1 = await phash("photo.jpg", 8);                      // file path
+const h2 = await phashBytes(new Uint8Array(jpegBytes), 8);   // raw bytes in memory
+console.log(h1.toString());                                  // "c3f8a1b27d0e4f96"
+```
+
+## Install (Browser)
+
+```ts
+import { phashBytes } from "rosetta-squint/browser";
+
+const resp = await fetch("/photo.jpg");
+const bytes = new Uint8Array(await resp.arrayBuffer());
+const h = await phashBytes(bytes, 8);
+console.log(h.toString());                                   // "c3f8a1b27d0e4f96"
+```
+
+The `/browser` sub-export omits the path-based functions (which use `node:fs`) and is otherwise identical. All 10 algorithms are available with the same names plus a `Bytes` suffix:
+
+`averageHashBytes`, `phashBytes`, `phashSimpleBytes`, `dhashBytes`, `dhashVerticalBytes`, `whashHaarBytes`, `whashDb4Bytes`, `whashDb4RobustBytes`, `colorhashBytes`, `cropResistantHashBytes`.
+
+### Via CDN
+
+Once on npm:
+
+```html
+<script type="module">
+  // esm.sh auto-builds browser bundles for any npm package
+  import { phashBytes } from "https://esm.sh/rosetta-squint/browser";
+
+  const resp = await fetch("/photo.jpg");
+  const bytes = new Uint8Array(await resp.arrayBuffer());
+  console.log((await phashBytes(bytes, 8)).toString());
+</script>
+```
+
+esm.sh handles the @jsquash WASM + libheif-js bundling automatically. Other CDN options (`unpkg`, `jsdelivr`) ship the raw `dist/` and assume your bundler handles CJS→ESM for the libheif-js and utif2 transitive deps.
+
+### Bundler notes
+
+The browser entry uses dynamic `import("libheif-js")` and `import("utif2")` which are CommonJS packages. Modern bundlers handle the CJS→ESM interop automatically:
+
+| Bundler | What you need |
+|---|---|
+| Vite | works out of the box |
+| esbuild | works out of the box |
+| webpack 5+ | works out of the box |
+| rollup | add `@rollup/plugin-commonjs` |
+| Parcel | works out of the box |
+
+WASM (mozjpeg, libwebp) is loaded via `WebAssembly.compileStreaming(fetch(url))` in the browser. Most bundlers emit the WASM blobs as static assets and rewrite the import URL — no manual config required for Vite/esbuild/webpack 5+.
+
+The `loadWasm` helper detects browser vs. Node at runtime and uses the right loader path. The `node:fs` import in the Node branch is dynamic (`await import("node:fs")`) so browser bundlers tree-shake it.
+
+## API
+
+```ts
+// Path entry (Node only)
+phash(path: string, hashSize: number): Promise<Hash>
+phashSimple(path: string, hashSize: number): Promise<Hash>
+dhash(path: string, hashSize: number): Promise<Hash>
+dhashVertical(path: string, hashSize: number): Promise<Hash>
+averageHash(path: string, hashSize: number): Promise<Hash>
+whashHaar(path: string, hashSize: number): Promise<Hash>
+whashDb4(path: string, hashSize: number): Promise<Hash>
+whashDb4Robust(path: string, hashSize: number): Promise<Hash>
+colorhash(path: string, binbits: number): Promise<Hash>
+cropResistantHash(path: string): Promise<ImageMultiHash>
+
+// Bytes entry (Node + browser)
+phashBytes(bytes: Uint8Array, hashSize: number): Promise<Hash>
+// ... same suffix-Bytes pattern for every algorithm above ...
+
+// Lower level
+decodeFile(path: string): Promise<RgbImage>        // Node only
+decodeBytes(bytes: Uint8Array): Promise<RgbImage>  // Node + browser
+```
+
+## Cross-port verification
+
+`phashBytes(imagehash.png, 8) === "ba8c84536bd3c366"` in this package's browser entry, this package's Node entry, the Go squint port, the Java squint port, and the Python `rosetta_squint` port. Same hex everywhere.
+
+## License
+
+BSD-2-Clause.

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "rosetta-squint",
+  "version": "1.0.0",
+  "description": "Cross-language byte-exact perceptual image hashing — decode + hash in one call. Umbrella package combining rosetta-squint-decode + rosetta-squint-hash.",
+  "keywords": [
+    "perceptual-hashing",
+    "imagehash",
+    "byte-exact",
+    "cross-language",
+    "image-decoder",
+    "phash"
+  ],
+  "homepage": "https://github.com/wmetcalf/rosetta-squint#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wmetcalf/rosetta-squint.git",
+    "directory": "squint/js/rosetta-squint"
+  },
+  "bugs": {
+    "url": "https://github.com/wmetcalf/rosetta-squint/issues"
+  },
+  "author": "Will Metcalf <william.metcalf@gmail.com>",
+  "license": "BSD-2-Clause",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    }
+  },
+  "engines": { "node": ">=18" },
+  "bin": {
+    "squint-cli": "./scripts/squint-cli.mjs"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "rosetta-squint-decode": "file:../../../decode/js/rosetta-squint-decode",
+    "rosetta-squint-hash": "file:../../../hash/js/rosetta-squint-hash",
+    "@jsquash/jpeg": "^1.6.0",
+    "@jsquash/webp": "^1.5.0",
+    "libheif-js": "1.17.1",
+    "pngjs": "^7",
+    "utif2": "^4.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5",
+    "vitest": "^2",
+    "@types/node": "^20"
+  }
+}

package/scripts/squint-cli.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import {
+  phash, phashSimple, dhash, dhashVertical, averageHash,
+  whashHaar, whashDb4, whashDb4Robust, colorhash, cropResistantHash,
+} from "../dist/index.js";
+
+const [, , algo, sizeStr, path] = process.argv;
+if (!algo || !sizeStr || !path) {
+  process.stderr.write("usage: squint-cli <algo> <size> <path>\n");
+  process.exit(2);
+}
+const size = parseInt(sizeStr, 10);
+
+const algos = {
+  phash, phash_simple: phashSimple, dhash, dhash_vertical: dhashVertical,
+  average_hash: averageHash, whash_haar: whashHaar, whash_db4: whashDb4,
+  whash_db4_robust: whashDb4Robust, colorhash,
+  crop_resistant_hash: cropResistantHash,
+};
+
+const fn = algos[algo];
+if (!fn) {
+  process.stderr.write(`unknown algo: ${algo}\n`);
+  process.exit(2);
+}
+
+try {
+  const result = algo === "crop_resistant_hash"
+    ? await cropResistantHash(path)
+    : await fn(path, size);
+  process.stdout.write(`${result.toString()}\n`);
+} catch (e) {
+  process.stderr.write(`error: ${e.message ?? e}\n`);
+  process.exit(1);
+}

package/src/browser.ts

@@ -0,0 +1,82 @@
+/**
+ * Browser entry for rosetta-squint.
+ *
+ * Same convenience API as the main entry except the path-based functions
+ * (which read from disk via `node:fs`) are omitted. Use the `_Bytes`
+ * variants in browsers; obtain bytes from `fetch(url).then(r => r.arrayBuffer())`,
+ * `FileReader`, drag-and-drop, etc.
+ *
+ *   import { phashBytes } from "rosetta-squint/browser";
+ *
+ *   const resp = await fetch("/photo.jpg");
+ *   const bytes = new Uint8Array(await resp.arrayBuffer());
+ *   const hash = await phashBytes(bytes, 8);
+ *   console.log(hash.toString());   // "c3f8a1b27d0e4f96"
+ *
+ * Underlying decoders (mozjpeg, libwebp, libheif) run in browser via WASM.
+ * TIFF (utif2) and HEIC (libheif-js) are CommonJS — your bundler must
+ * support CJS→ESM interop (esbuild, vite, webpack 5+, rollup with
+ * @rollup/plugin-commonjs all do).
+ */
+
+import { decode, type DecodedImage } from "rosetta-squint-decode";
+import * as rih from "rosetta-squint-hash/browser";
+
+export type { Hash, RgbImage } from "rosetta-squint-hash/browser";
+export type { Format } from "rosetta-squint-decode";
+export {
+  ImageMultiHash,
+  hexToHash,
+  hexToFlathash,
+  hexToMultiHash,
+} from "rosetta-squint-hash/browser";
+
+function decodedToRgbImage(d: DecodedImage): rih.RgbImage {
+  return {
+    width: d.width,
+    height: d.height,
+    data: d.data,
+    channels: d.channels,
+  };
+}
+
+export async function decodeBytes(bytes: Uint8Array): Promise<rih.RgbImage> {
+  const decoded = await decode(bytes);
+  return decodedToRgbImage(decoded);
+}
+
+// Bytes-based convenience hash functions (no path variants in browser).
+
+export async function averageHashBytes(bytes: Uint8Array, hashSize: number): Promise<rih.Hash> {
+  return rih.averageHash(await decodeBytes(bytes), hashSize);
+}
+export async function phashBytes(bytes: Uint8Array, hashSize: number): Promise<rih.Hash> {
+  return rih.phash(await decodeBytes(bytes), hashSize);
+}
+export async function phashSimpleBytes(bytes: Uint8Array, hashSize: number): Promise<rih.Hash> {
+  return rih.phashSimple(await decodeBytes(bytes), hashSize);
+}
+export async function dhashBytes(bytes: Uint8Array, hashSize: number): Promise<rih.Hash> {
+  return rih.dhash(await decodeBytes(bytes), hashSize);
+}
+export async function dhashVerticalBytes(bytes: Uint8Array, hashSize: number): Promise<rih.Hash> {
+  return rih.dhashVertical(await decodeBytes(bytes), hashSize);
+}
+export async function whashHaarBytes(bytes: Uint8Array, hashSize: number): Promise<rih.Hash> {
+  return rih.whashHaar(await decodeBytes(bytes), hashSize);
+}
+export async function whashDb4Bytes(bytes: Uint8Array, hashSize: number): Promise<rih.Hash> {
+  return rih.whashDb4(await decodeBytes(bytes), hashSize);
+}
+export async function whashDb4RobustBytes(bytes: Uint8Array, hashSize: number): Promise<rih.Hash> {
+  return rih.whashDb4Robust(await decodeBytes(bytes), hashSize);
+}
+export async function colorhashBytes(bytes: Uint8Array, binbits: number): Promise<rih.Hash> {
+  return rih.colorhash(await decodeBytes(bytes), binbits);
+}
+export async function cropResistantHashBytes(
+  bytes: Uint8Array,
+  limitSegments?: number,
+) {
+  return rih.cropResistantHash(await decodeBytes(bytes), limitSegments);
+}

package/src/index.ts

@@ -0,0 +1,183 @@
+import { open, lstat } from "node:fs/promises";
+import { decode, type DecodedImage } from "rosetta-squint-decode";
+import * as rih from "rosetta-squint-hash";
+
+// Re-export key types and utilities from the underlying packages for ergonomics.
+export type { Hash } from "rosetta-squint-hash";
+export type { Format } from "rosetta-squint-decode";
+export { ImageMultiHash, hexToHash, hexToFlathash, hexToMultiHash } from "rosetta-squint-hash";
+
+/**
+ * Maximum allowed size for path-based decode inputs. Refuse anything larger
+ * BEFORE reading bytes. Callers that genuinely need to process images larger
+ * than this should decode via rosetta-squint-decode directly after explicit
+ * validation.
+ */
+export const MAX_FILE_SIZE = 256 * 1024 * 1024; // 256 MiB
+
+/** Adapt a rosetta-squint-decode DecodedImage into the rosetta-squint-hash RgbImage shape. */
+function decodedToRgbImage(d: DecodedImage): rih.RgbImage {
+    return {
+        width: d.width,
+        height: d.height,
+        data: d.data,
+        channels: d.channels,
+    };
+}
+
+/** Decode raw bytes (any supported format) into the rgb image shape used by the hash lib. */
+export async function decodeBytes(bytes: Uint8Array): Promise<rih.RgbImage> {
+    const decoded = await decode(bytes);
+    return decodedToRgbImage(decoded);
+}
+
+/** Read a file from disk and decode.
+ *
+ * Refuses symlinks (via `lstat`), non-regular files (FIFOs, /dev/zero,
+ * character devices, etc.) and files larger than MAX_FILE_SIZE BEFORE
+ * reading bytes — without these guards `readFile("/dev/zero")` would loop
+ * until OOM and a 300 MiB sparse file would allocate 300 MiB even though
+ * it contains no image. Callers who genuinely want symlink resolution
+ * must do it explicitly (e.g. `fs.promises.realpath`) before calling
+ * this function.
+ *
+ * Node's `fs.open` doesn't directly expose `O_NOFOLLOW`, so we lstat the
+ * path first and reject symlinks. The window between the lstat and the
+ * subsequent open is narrow — the attacker would have to swap the target
+ * between those two syscalls, much harder than swapping the symlink
+ * destination across an unrelated stat→read window.
+ *
+ * The file is then opened ONCE via `fs.open`, and `fhandle.stat()` plus
+ * `fhandle.read()` operate on the same fd. `fhandle.stat()` ultimately
+ * calls fstat(2) on the open descriptor, not stat(2) on the path, which
+ * closes the TOCTOU window between the size check and the read. The read
+ * is bounded by `MAX_FILE_SIZE + 1` so a concurrent writer that grows the
+ * file after the size check is still rejected.
+ */
+export async function decodeFile(path: string): Promise<rih.RgbImage> {
+    // Lstat-then-open is unfortunately not atomic on Node — there's no
+    // public API for O_NOFOLLOW. The race is much narrower than the
+    // stat→read race we already close below.
+    const linkStat = await lstat(path);
+    if (linkStat.isSymbolicLink()) {
+        throw new TypeError(`symlink not allowed: ${path}`);
+    }
+    const fh = await open(path, "r");
+    try {
+        const st = await fh.stat();
+        if (!st.isFile()) {
+            throw new Error(`not a regular file: ${path}`);
+        }
+        if (st.size > MAX_FILE_SIZE) {
+            throw new Error(
+                `input file too large: ${st.size} bytes (max ${MAX_FILE_SIZE} `
+                + `bytes / 256 MiB). For images above this threshold, decode `
+                + `via rosetta-squint-decode directly after explicit validation.`,
+            );
+        }
+        // Read up to MAX_FILE_SIZE+1 bytes so a concurrent writer that
+        // grows the file post-stat is rejected rather than silently
+        // exceeding the cap.
+        const cap = Math.min(st.size, MAX_FILE_SIZE) + 1;
+        const buf = new Uint8Array(cap);
+        let total = 0;
+        while (total < cap) {
+            const { bytesRead } = await fh.read(
+                buf, total, cap - total, total,
+            );
+            if (bytesRead === 0) break;
+            total += bytesRead;
+        }
+        if (total > MAX_FILE_SIZE) {
+            throw new Error(
+                `input file too large: ${total} bytes (max ${MAX_FILE_SIZE} `
+                + `bytes / 256 MiB). For images above this threshold, decode `
+                + `via rosetta-squint-decode directly after explicit validation.`,
+            );
+        }
+        const bytes = buf.subarray(0, total);
+        return decodeBytes(bytes);
+    } finally {
+        await fh.close();
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Convenience hash functions — each accepts either a file path or raw bytes.
+// ---------------------------------------------------------------------------
+
+export async function averageHash(path: string, hashSize: number): Promise<rih.Hash> {
+    return rih.averageHash(await decodeFile(path), hashSize);
+}
+export async function averageHashBytes(bytes: Uint8Array, hashSize: number): Promise<rih.Hash> {
+    return rih.averageHash(await decodeBytes(bytes), hashSize);
+}
+
+export async function phash(path: string, hashSize: number): Promise<rih.Hash> {
+    return rih.phash(await decodeFile(path), hashSize);
+}
+export async function phashBytes(bytes: Uint8Array, hashSize: number): Promise<rih.Hash> {
+    return rih.phash(await decodeBytes(bytes), hashSize);
+}
+
+export async function phashSimple(path: string, hashSize: number): Promise<rih.Hash> {
+    return rih.phashSimple(await decodeFile(path), hashSize);
+}
+export async function phashSimpleBytes(bytes: Uint8Array, hashSize: number): Promise<rih.Hash> {
+    return rih.phashSimple(await decodeBytes(bytes), hashSize);
+}
+
+export async function dhash(path: string, hashSize: number): Promise<rih.Hash> {
+    return rih.dhash(await decodeFile(path), hashSize);
+}
+export async function dhashBytes(bytes: Uint8Array, hashSize: number): Promise<rih.Hash> {
+    return rih.dhash(await decodeBytes(bytes), hashSize);
+}
+
+export async function dhashVertical(path: string, hashSize: number): Promise<rih.Hash> {
+    return rih.dhashVertical(await decodeFile(path), hashSize);
+}
+export async function dhashVerticalBytes(bytes: Uint8Array, hashSize: number): Promise<rih.Hash> {
+    return rih.dhashVertical(await decodeBytes(bytes), hashSize);
+}
+
+export async function whashHaar(path: string, hashSize: number): Promise<rih.Hash> {
+    return rih.whashHaar(await decodeFile(path), hashSize);
+}
+export async function whashHaarBytes(bytes: Uint8Array, hashSize: number): Promise<rih.Hash> {
+    return rih.whashHaar(await decodeBytes(bytes), hashSize);
+}
+
+export async function whashDb4(path: string, hashSize: number): Promise<rih.Hash> {
+    return rih.whashDb4(await decodeFile(path), hashSize);
+}
+export async function whashDb4Bytes(bytes: Uint8Array, hashSize: number): Promise<rih.Hash> {
+    return rih.whashDb4(await decodeBytes(bytes), hashSize);
+}
+
+export async function whashDb4Robust(path: string, hashSize: number): Promise<rih.Hash> {
+    return rih.whashDb4Robust(await decodeFile(path), hashSize);
+}
+export async function whashDb4RobustBytes(bytes: Uint8Array, hashSize: number): Promise<rih.Hash> {
+    return rih.whashDb4Robust(await decodeBytes(bytes), hashSize);
+}
+
+export async function colorhash(path: string, binbits: number): Promise<rih.Hash> {
+    return rih.colorhash(await decodeFile(path), binbits);
+}
+export async function colorhashBytes(bytes: Uint8Array, binbits: number): Promise<rih.Hash> {
+    return rih.colorhash(await decodeBytes(bytes), binbits);
+}
+
+export async function cropResistantHash(
+    path: string,
+    limitSegments?: number,
+): Promise<rih.ImageMultiHash> {
+    return rih.cropResistantHash(await decodeFile(path), limitSegments);
+}
+export async function cropResistantHashBytes(
+    bytes: Uint8Array,
+    limitSegments?: number,
+): Promise<rih.ImageMultiHash> {
+    return rih.cropResistantHash(await decodeBytes(bytes), limitSegments);
+}

package/tests/browser-entry.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Browser-entry smoke test for rosetta-squint.
+ *
+ * Imports `rosetta-squint/browser` and verifies:
+ *   1. All bytes-based convenience functions are exported and callable
+ *   2. Path-based functions are NOT exported (no `node:fs`)
+ *   3. Hash output matches the main entry for the same byte input
+ *      (no behavioral drift between entries)
+ *
+ * vitest runs this in Node, so we can't directly verify browser execution,
+ * but the import-tree check + dynamic-import-of-node:fs branch logic in
+ * loadWasm.ts means the same dist/browser.js bundle that loads here will
+ * load in browsers when fetched via CDN / served by a bundler.
+ */
+
+import { describe, expect, it } from "vitest";
+import { readFile } from "node:fs/promises";
+import * as browserEntry from "../src/browser.js";
+import * as mainEntry from "../src/index.js";
+
+const FIXTURES = new URL("../../../../hash/spec/fixtures/", import.meta.url);
+
+describe("rosetta-squint/browser entry", () => {
+  it("exposes bytes-based functions for all 10 algorithms", () => {
+    expect(typeof browserEntry.averageHashBytes).toBe("function");
+    expect(typeof browserEntry.phashBytes).toBe("function");
+    expect(typeof browserEntry.phashSimpleBytes).toBe("function");
+    expect(typeof browserEntry.dhashBytes).toBe("function");
+    expect(typeof browserEntry.dhashVerticalBytes).toBe("function");
+    expect(typeof browserEntry.whashHaarBytes).toBe("function");
+    expect(typeof browserEntry.whashDb4Bytes).toBe("function");
+    expect(typeof browserEntry.whashDb4RobustBytes).toBe("function");
+    expect(typeof browserEntry.colorhashBytes).toBe("function");
+    expect(typeof browserEntry.cropResistantHashBytes).toBe("function");
+    expect(typeof browserEntry.decodeBytes).toBe("function");
+  });
+
+  it("does NOT expose path-based functions (no node:fs)", () => {
+    // @ts-expect-error — phash (path) is intentionally not exported from /browser
+    expect(browserEntry.phash).toBeUndefined();
+    // @ts-expect-error
+    expect(browserEntry.decodeFile).toBeUndefined();
+  });
+
+  it("phashBytes on imagehash.png matches main entry's phash", async () => {
+    const path = new URL("imagehash.png", FIXTURES);
+    const bytes = new Uint8Array(await readFile(path));
+    const hBrowser = await browserEntry.phashBytes(bytes, 8);
+    const hMain = await mainEntry.phashBytes(bytes, 8);
+    expect(hBrowser.toString()).toBe(hMain.toString());
+    // And matches the cross-port reference value from Go/Java/JS reports
+    expect(hBrowser.toString()).toBe("ba8c84536bd3c366");
+  });
+
+  it("dhashBytes on imagehash.png produces non-empty hex", async () => {
+    const path = new URL("imagehash.png", FIXTURES);
+    const bytes = new Uint8Array(await readFile(path));
+    const h = await browserEntry.dhashBytes(bytes, 8);
+    expect(h.toString()).toMatch(/^[0-9a-f]+$/);
+    expect(h.toString().length).toBe(16);
+  });
+
+  it("decodeBytes produces an RgbImage shape", async () => {
+    const path = new URL("imagehash.png", FIXTURES);
+    const bytes = new Uint8Array(await readFile(path));
+    const img = await browserEntry.decodeBytes(bytes);
+    expect(img.width).toBeGreaterThan(0);
+    expect(img.height).toBeGreaterThan(0);
+    expect(img.channels === 3 || img.channels === 4).toBe(true);
+    expect(img.data.byteLength).toBe(img.width * img.height * img.channels);
+  });
+});

package/tests/integration.test.ts

@@ -0,0 +1,325 @@
+import { describe, it, expect } from "vitest";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+    phash, phashBytes,
+    averageHash, averageHashBytes,
+    dhash, dhashBytes,
+    dhashVertical, dhashVerticalBytes,
+    phashSimple, phashSimpleBytes,
+    whashHaar, whashHaarBytes,
+    whashDb4, whashDb4Bytes,
+    colorhash, colorhashBytes,
+    cropResistantHash, cropResistantHashBytes,
+    decodeFile,
+    hexToHash, hexToFlathash, hexToMultiHash,
+    ImageMultiHash,
+} from "../src/index.js";
+import * as rih from "rosetta-squint-hash";
+
+const FIXTURES_PNG = join(
+    new URL(".", import.meta.url).pathname,
+    "../../../../decode/spec/fixtures/png/valid",
+);
+const FIXTURES_JPEG = join(
+    new URL(".", import.meta.url).pathname,
+    "../../../../decode/spec/fixtures/jpeg/valid",
+);
+
+const PNG_FILES = [
+    "imagehash.png",
+    "peppers.png",
+    "checker-256.png",
+];
+const JPEG_FILES = [
+    "larger-photo-128.jpg",
+    "64x64-quality-50.jpg",
+];
+
+// ---------------------------------------------------------------------------
+// phash
+// ---------------------------------------------------------------------------
+describe("phash", () => {
+    for (const name of PNG_FILES) {
+        const path = join(FIXTURES_PNG, name);
+
+        it(`returns a Hash for ${name}`, async () => {
+            const h = await phash(path, 8);
+            expect(h).toBeInstanceOf(rih.Hash);
+            expect(h.toHex().length).toBe(16); // 8*8 bits = 64 bits = 16 hex chars
+        });
+
+        it(`phash === phashBytes for ${name}`, async () => {
+            const [hPath, hBytes] = await Promise.all([
+                phash(path, 8),
+                readFile(path).then(b => phashBytes(new Uint8Array(b), 8)),
+            ]);
+            expect(hPath.toHex()).toBe(hBytes.toHex());
+        });
+
+        it(`phash matches rih.phash(decodeFile) for ${name}`, async () => {
+            const [hSquint, img] = await Promise.all([
+                phash(path, 8),
+                decodeFile(path),
+            ]);
+            const hRih = rih.phash(img, 8);
+            expect(hSquint.toHex()).toBe(hRih.toHex());
+        });
+    }
+
+    for (const name of JPEG_FILES) {
+        const path = join(FIXTURES_JPEG, name);
+
+        it(`returns a Hash for ${name}`, async () => {
+            const h = await phash(path, 8);
+            expect(h).toBeInstanceOf(rih.Hash);
+        });
+
+        it(`phash === phashBytes for ${name}`, async () => {
+            const [hPath, hBytes] = await Promise.all([
+                phash(path, 8),
+                readFile(path).then(b => phashBytes(new Uint8Array(b), 8)),
+            ]);
+            expect(hPath.toHex()).toBe(hBytes.toHex());
+        });
+    }
+});
+
+// ---------------------------------------------------------------------------
+// averageHash
+// ---------------------------------------------------------------------------
+describe("averageHash", () => {
+    for (const name of PNG_FILES) {
+        const path = join(FIXTURES_PNG, name);
+
+        it(`returns a Hash for ${name}`, async () => {
+            const h = await averageHash(path, 8);
+            expect(h).toBeInstanceOf(rih.Hash);
+        });
+
+        it(`averageHash === averageHashBytes for ${name}`, async () => {
+            const [hPath, hBytes] = await Promise.all([
+                averageHash(path, 8),
+                readFile(path).then(b => averageHashBytes(new Uint8Array(b), 8)),
+            ]);
+            expect(hPath.toHex()).toBe(hBytes.toHex());
+        });
+
+        it(`averageHash matches rih.averageHash(decodeFile) for ${name}`, async () => {
+            const [hSquint, img] = await Promise.all([
+                averageHash(path, 8),
+                decodeFile(path),
+            ]);
+            const hRih = rih.averageHash(img, 8);
+            expect(hSquint.toHex()).toBe(hRih.toHex());
+        });
+    }
+});
+
+// ---------------------------------------------------------------------------
+// dhash
+// ---------------------------------------------------------------------------
+describe("dhash", () => {
+    for (const name of ["imagehash.png", "checker-256.png"]) {
+        const path = join(FIXTURES_PNG, name);
+
+        it(`returns a Hash for ${name}`, async () => {
+            const h = await dhash(path, 8);
+            expect(h).toBeInstanceOf(rih.Hash);
+        });
+
+        it(`dhash === dhashBytes for ${name}`, async () => {
+            const [hPath, hBytes] = await Promise.all([
+                dhash(path, 8),
+                readFile(path).then(b => dhashBytes(new Uint8Array(b), 8)),
+            ]);
+            expect(hPath.toHex()).toBe(hBytes.toHex());
+        });
+    }
+});
+
+// ---------------------------------------------------------------------------
+// dhashVertical
+// ---------------------------------------------------------------------------
+describe("dhashVertical", () => {
+    for (const name of ["imagehash.png", "checker-256.png"]) {
+        const path = join(FIXTURES_PNG, name);
+
+        it(`returns a Hash for ${name}`, async () => {
+            const h = await dhashVertical(path, 8);
+            expect(h).toBeInstanceOf(rih.Hash);
+        });
+
+        it(`dhashVertical === dhashVerticalBytes for ${name}`, async () => {
+            const [hPath, hBytes] = await Promise.all([
+                dhashVertical(path, 8),
+                readFile(path).then(b => dhashVerticalBytes(new Uint8Array(b), 8)),
+            ]);
+            expect(hPath.toHex()).toBe(hBytes.toHex());
+        });
+    }
+});
+
+// ---------------------------------------------------------------------------
+// phashSimple
+// ---------------------------------------------------------------------------
+describe("phashSimple", () => {
+    for (const name of ["imagehash.png", "peppers.png"]) {
+        const path = join(FIXTURES_PNG, name);
+
+        it(`returns a Hash for ${name}`, async () => {
+            const h = await phashSimple(path, 8);
+            expect(h).toBeInstanceOf(rih.Hash);
+        });
+
+        it(`phashSimple === phashSimpleBytes for ${name}`, async () => {
+            const [hPath, hBytes] = await Promise.all([
+                phashSimple(path, 8),
+                readFile(path).then(b => phashSimpleBytes(new Uint8Array(b), 8)),
+            ]);
+            expect(hPath.toHex()).toBe(hBytes.toHex());
+        });
+    }
+});
+
+// ---------------------------------------------------------------------------
+// whashHaar
+// ---------------------------------------------------------------------------
+describe("whashHaar", () => {
+    for (const name of ["imagehash.png", "peppers.png"]) {
+        const path = join(FIXTURES_PNG, name);
+
+        it(`returns a Hash for ${name}`, async () => {
+            const h = await whashHaar(path, 8);
+            expect(h).toBeInstanceOf(rih.Hash);
+        });
+
+        it(`whashHaar === whashHaarBytes for ${name}`, async () => {
+            const [hPath, hBytes] = await Promise.all([
+                whashHaar(path, 8),
+                readFile(path).then(b => whashHaarBytes(new Uint8Array(b), 8)),
+            ]);
+            expect(hPath.toHex()).toBe(hBytes.toHex());
+        });
+    }
+});
+
+// ---------------------------------------------------------------------------
+// whashDb4
+// ---------------------------------------------------------------------------
+describe("whashDb4", () => {
+    for (const name of ["imagehash.png", "peppers.png"]) {
+        const path = join(FIXTURES_PNG, name);
+
+        it(`returns a Hash for ${name}`, async () => {
+            const h = await whashDb4(path, 8);
+            expect(h).toBeInstanceOf(rih.Hash);
+        });
+
+        it(`whashDb4 === whashDb4Bytes for ${name}`, async () => {
+            const [hPath, hBytes] = await Promise.all([
+                whashDb4(path, 8),
+                readFile(path).then(b => whashDb4Bytes(new Uint8Array(b), 8)),
+            ]);
+            expect(hPath.toHex()).toBe(hBytes.toHex());
+        });
+    }
+});
+
+// ---------------------------------------------------------------------------
+// colorhash
+// ---------------------------------------------------------------------------
+describe("colorhash", () => {
+    for (const name of ["imagehash.png", "peppers.png"]) {
+        const path = join(FIXTURES_PNG, name);
+
+        it(`returns a Hash for ${name}`, async () => {
+            const h = await colorhash(path, 3);
+            expect(h).toBeInstanceOf(rih.Hash);
+        });
+
+        it(`colorhash === colorhashBytes for ${name}`, async () => {
+            const [hPath, hBytes] = await Promise.all([
+                colorhash(path, 3),
+                readFile(path).then(b => colorhashBytes(new Uint8Array(b), 3)),
+            ]);
+            expect(hPath.toHex()).toBe(hBytes.toHex());
+        });
+
+        it(`colorhash matches rih.colorhash(decodeFile) for ${name}`, async () => {
+            const [hSquint, img] = await Promise.all([
+                colorhash(path, 3),
+                decodeFile(path),
+            ]);
+            const hRih = rih.colorhash(img, 3);
+            expect(hSquint.toHex()).toBe(hRih.toHex());
+        });
+    }
+});
+
+// ---------------------------------------------------------------------------
+// cropResistantHash
+// ---------------------------------------------------------------------------
+describe("cropResistantHash", () => {
+    for (const name of ["imagehash.png", "peppers.png"]) {
+        const path = join(FIXTURES_PNG, name);
+
+        it(`returns an ImageMultiHash for ${name}`, async () => {
+            const mh = await cropResistantHash(path);
+            expect(mh).toBeInstanceOf(ImageMultiHash);
+            expect(mh.segmentHashes.length).toBeGreaterThan(0);
+        });
+
+        it(`cropResistantHash === cropResistantHashBytes for ${name}`, async () => {
+            const [mhPath, mhBytes] = await Promise.all([
+                cropResistantHash(path),
+                readFile(path).then(b => cropResistantHashBytes(new Uint8Array(b))),
+            ]);
+            expect(mhPath.toString()).toBe(mhBytes.toString());
+        });
+
+        it(`cropResistantHash matches rih.cropResistantHash(decodeFile) for ${name}`, async () => {
+            const [mhSquint, img] = await Promise.all([
+                cropResistantHash(path),
+                decodeFile(path),
+            ]);
+            const mhRih = rih.cropResistantHash(img);
+            expect(mhSquint.toString()).toBe(mhRih.toString());
+        });
+    }
+});
+
+// ---------------------------------------------------------------------------
+// Re-export sanity checks
+// ---------------------------------------------------------------------------
+describe("re-exports", () => {
+    it("hexToHash round-trips a 16-char hex string", () => {
+        const hex = "ffffffffffffffff";
+        const h = hexToHash(hex);
+        expect(h.toHex()).toBe(hex);
+    });
+
+    it("hexToFlathash round-trips a colorhash string", async () => {
+        const path = join(FIXTURES_PNG, "imagehash.png");
+        const h = await colorhash(path, 3);
+        const hex = h.toHex();
+        const h2 = hexToFlathash(hex, 3);
+        expect(h2.toHex()).toBe(hex);
+    });
+
+    it("hexToMultiHash round-trips a cropResistantHash string", async () => {
+        const path = join(FIXTURES_PNG, "imagehash.png");
+        const mh = await cropResistantHash(path);
+        const str = mh.toString();
+        const mh2 = hexToMultiHash(str);
+        expect(mh2.toString()).toBe(str);
+    });
+
+    it("ImageMultiHash is exported and constructible", () => {
+        const bits = [[true, false], [false, true]];
+        const h = new rih.Hash(bits);
+        const mh = new ImageMultiHash([h]);
+        expect(mh.segmentHashes.length).toBe(1);
+    });
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "strict": true,
+    "declaration": true,
+    "outDir": "dist",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "noUncheckedIndexedAccess": false
+  },
+  "include": ["src/**/*"]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["tests/**/*.test.ts"],
+  },
+});