roxify 1.1.1 → 1.1.2

package/README.md

@@ -6,7 +6,15 @@ Encode binary data into PNG images and decode them back. Supports CLI and progra
 
 Roxify is a compact, color-based alternative to QR codes, designed specifically for digital-only use (not for printing). It encodes data using color channels (rather than monochrome patterns) for higher density, and is optimized for decoding from approximate screenshots — including nearest-neighbour resize/stretch and solid or gradient backgrounds. It is not intended for printed media and is not resilient to lossy compression or heavy image filtering.
 
-Roxified PNGs are often more space-efficient than ZIP archives for similar payloads and provide a visual indication of the embedded data size.
+Roxify creates PNGs that are often more space-efficient than ZIP or 7z archives for similar payloads without loss. Roxify provides superior compression ratios, making it ideal for embedding images, GIFs, audio, video, code, and other files without any quality loss — the original file is perfectly recovered upon decoding.
+
+Key benefits:
+
+- **Superior Compression**: Roxify outperforms traditional ZIP and 7z (LZMA) in speed and ratio, enabling smaller PNG outputs.
+- **Lossless Embedding**: Compress and embed any file type (images, videos, code) with full fidelity restoration.
+- **Code Efficiency**: Hyper-efficient for compressing source code, reducing file sizes dramatically.
+- **Obfuscation & Security**: Obfuscate code or lock files with AES-256-GCM encryption, more compact than password-protected ZIPs.
+- **Visual Data Indicator**: PNG size visually represents embedded data size, providing an intuitive overview.
 
 ## Installation
 
@@ -36,7 +44,7 @@ If no output name is provided:
 
 - `-p, --passphrase <pass>` — Encrypt with AES-256-GCM
 - `-m, --mode <mode>` — Encoding mode: `screenshot` (default), `pixel`, `compact`, `chunk`
-- `-q, --quality <0-11>` — Brotli compression quality (default: 11)
+- `-q, --quality <0-22>` — Roxify compression level (default: 22)
 - `--no-compress` — Disable compression
 - `-v, --verbose` — Show detailed errors
 
@@ -68,8 +76,8 @@ console.log(meta?.name);
 - `mode` — `'screenshot'` | `'pixel'` | `'compact'` | `'chunk'` (default: `'screenshot'`)
 - `name` — Original filename (embedded as metadata)
 - `passphrase` — Encryption passphrase (uses AES-256-GCM)
-- `compression` — `'br'` | `'none'` (default: `'br'`)
-- `brQuality` — Brotli quality 0-11 (default: 4)
+- `compression` — `'Roxify'` | `'none'` (default: `'Roxify'`)
+- `brQuality` — Roxify compression level 0-22 (default: 22)
 
 ## Example: Express Endpoint
 

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { readFileSync, writeFileSync } from 'fs';
-import { basename, resolve } from 'path';
+import { basename, dirname, join, resolve } from 'path';
+import sharp from 'sharp';
 import { cropAndReconstitute, DataFormatError, decodePngToBinary, encodeBinaryToPng, IncorrectPassphraseError, PassphraseRequiredError, } from './index.js';
 const VERSION = '1.0.4';
 function showHelp() {
@@ -22,6 +23,7 @@ Options:
   --no-compress             Disable compression
   -o, --output <path>       Output file path
   --view-reconst            Export the reconstituted PNG for debugging
+  --debug                   Export debug images (doubled.png, reconstructed.png)
   -v, --verbose             Show detailed errors
 
 Run "npx rox help" for this message.
@@ -46,6 +48,10 @@ function parseArgs(args) {
                 parsed.viewReconst = true;
                 i++;
             }
+            else if (key === 'debug') {
+                parsed.debug = true;
+                i++;
+            }
             else if (key === 'debug-dir') {
                 parsed.debugDir = args[i + 1];
                 i += 2;
@@ -159,33 +165,33 @@ async function decodeCommand(args) {
     }
     const resolvedInput = resolve(inputPath);
     try {
-        let inputBuffer = readFileSync(resolvedInput);
-        let resolvedInputPath = resolvedInput;
-        try {
-            const reconst = await cropAndReconstitute(inputBuffer);
-            inputBuffer = reconst;
-            resolvedInputPath = resolvedInput.replace(/(\.\w+)?$/, '_reconst.png');
-            if (parsed.viewReconst) {
-                writeFileSync(resolvedInputPath, reconst);
-                console.log(`Reconst PNG: ${resolvedInputPath}`);
-            }
-        }
-        catch (e) {
-            console.log('Could not generate reconst PNG:', e.message);
-        }
-        console.log(`Reading: ${resolvedInputPath.replace('_reconst.png', '.png')}`);
+        const inputBuffer = readFileSync(resolvedInput);
+        console.log(`Reading: ${resolvedInput}`);
+        const info = await sharp(inputBuffer).metadata();
         const options = {};
         if (parsed.passphrase) {
             options.passphrase = parsed.passphrase;
         }
-        if (parsed.debugDir) {
-            options.debugDir = parsed.debugDir;
+        if (parsed.debug) {
+            options.debugDir = dirname(resolvedInput);
         }
         console.log(`Decoding...`);
         const startDecode = Date.now();
         if (parsed.verbose)
             options.verbose = true;
-        const result = await decodePngToBinary(inputBuffer, options);
+        const doubledBuffer = await sharp(inputBuffer)
+            .resize({
+            width: info.width * 2,
+            height: info.height * 2,
+            kernel: 'nearest',
+        })
+            .png()
+            .toBuffer();
+        if (options.debugDir) {
+            writeFileSync(join(options.debugDir, 'doubled.png'), doubledBuffer);
+        }
+        const reconstructedBuffer = await cropAndReconstitute(doubledBuffer, options.debugDir);
+        const result = await decodePngToBinary(reconstructedBuffer, options);
         const decodeTime = Date.now() - startDecode;
         const resolvedOutput = parsed.output || outputPath || result.meta?.name || 'decoded.bin';
         writeFileSync(resolvedOutput, result.buf);

package/dist/index.d.ts

@@ -16,11 +16,10 @@ export declare class DataFormatError extends Error {
 export interface EncodeOptions {
     /**
      * Compression algorithm to use.
-     * - `'br'`: Brotli compression (default for most modes)
-     * - `'none'`: No compression
-     * @defaultValue `'br'` for most modes
+     * - `'zstd'`: Zstandard compression (maximum compression for smallest files)
+     * @defaultValue `'zstd'`
      */
-    compression?: 'br' | 'none';
+    compression?: 'zstd';
     /**
      * Passphrase for encryption. If provided without `encrypt` option, defaults to AES-256-GCM.
      */
@@ -91,7 +90,21 @@ export interface DecodeResult {
         name?: string;
     };
 }
-export declare function cropAndReconstitute(input: Buffer): Promise<Buffer>;
+/**
+ * Options for decoding a PNG back to binary data.
+ * @public
+ */
+export interface DecodeOptions {
+    /**
+     * Passphrase for encrypted inputs.
+     */
+    passphrase?: string;
+    /**
+     * Directory to save debug images (doubled.png, reconstructed.png).
+     */
+    debugDir?: string;
+}
+export declare function cropAndReconstitute(input: Buffer, debugDir?: string): Promise<Buffer>;
 /**
  * Encode a Buffer into a PNG wrapper. Supports optional compression and
  * encryption. Defaults are chosen for a good balance between speed and size.
@@ -109,6 +122,4 @@ export declare function encodeBinaryToPng(input: Buffer, opts?: EncodeOptions):
  * @param opts - Options (passphrase for encrypted inputs)
  * @public
  */
-export declare function decodePngToBinary(pngBuf: Buffer, opts?: {
-    passphrase?: string;
-}): Promise<DecodeResult>;
+export declare function decodePngToBinary(pngBuf: Buffer, opts?: DecodeOptions): Promise<DecodeResult>;

package/dist/index.js

@@ -1,4 +1,6 @@
+import { compress as zstdCompress, decompress as zstdDecompress, } from '@mongodb-js/zstd';
 import { createCipheriv, createDecipheriv, pbkdf2Sync, randomBytes, } from 'crypto';
+import { join } from 'path';
 import encode from 'png-chunks-encode';
 import extract from 'png-chunks-extract';
 import sharp from 'sharp';
@@ -38,6 +40,9 @@ const MARKER_COLORS = [
 ];
 const MARKER_START = MARKER_COLORS;
 const MARKER_END = [...MARKER_COLORS].reverse();
+const COMPRESSION_MARKERS = {
+    zstd: [{ r: 0, g: 255, b: 0 }],
+};
 function colorsToBytes(colors) {
     const buf = Buffer.alloc(colors.length * 3);
     for (let i = 0; i < colors.length; i++) {
@@ -58,6 +63,15 @@ function applyXor(buf, passphrase) {
 function tryBrotliDecompress(payload) {
     return Buffer.from(zlib.brotliDecompressSync(payload));
 }
+async function tryZstdDecompress(payload) {
+    try {
+        const result = await zstdDecompress(payload);
+        return Buffer.from(result);
+    }
+    catch {
+        return payload;
+    }
+}
 function tryDecryptIfNeeded(buf, passphrase) {
     if (!buf || buf.length === 0)
         return buf;
@@ -107,7 +121,7 @@ async function loadRaw(imgInput) {
         .toBuffer({ resolveWithObject: true });
     return { data, info };
 }
-export async function cropAndReconstitute(input) {
+export async function cropAndReconstitute(input, debugDir) {
     async function loadRaw(imgInput) {
         const { data, info } = await sharp(imgInput)
             .ensureAlpha()
@@ -122,11 +136,28 @@ export async function cropAndReconstitute(input) {
         return a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
     }
     const { data, info } = await loadRaw(input);
-    const w = info.width;
-    const h = info.height;
+    const doubledBuffer = await sharp(input)
+        .resize({
+        width: info.width * 2,
+        height: info.height * 2,
+        kernel: 'nearest',
+    })
+        .png()
+        .toBuffer();
+    if (debugDir) {
+        await sharp(doubledBuffer).toFile(join(debugDir, 'doubled.png'));
+    }
+    const { data: doubledData, info: doubledInfo } = await loadRaw(doubledBuffer);
+    const w = doubledInfo.width;
+    const h = doubledInfo.height;
     function at(x, y) {
         const i = idxFor(x, y, w);
-        return [data[i], data[i + 1], data[i + 2], data[i + 3]];
+        return [
+            doubledData[i],
+            doubledData[i + 1],
+            doubledData[i + 2],
+            doubledData[i + 3],
+        ];
     }
     let startPoint = null;
     for (let y = 0; y < h && !startPoint; y++) {
@@ -200,7 +231,7 @@ export async function cropAndReconstitute(input) {
     const cropH = sy2 - sy1 + 1;
     if (cropW <= 0 || cropH <= 0)
         throw new Error('Invalid crop dimensions');
-    const cropped = await sharp(input)
+    const cropped = await sharp(doubledBuffer)
         .extract({ left: sx1, top: sy1, width: cropW, height: cropH })
         .png()
         .toBuffer();
@@ -240,25 +271,13 @@ export async function cropAndReconstitute(input) {
             out[dstI + 3] = cdata[srcI + 3];
         }
     }
-    if (cw >= 3) {
-        const targetY = ch - 1;
-        for (let x = cw - 3; x < cw; x++) {
-            const i = ((targetY * newWidth + x) * 4) | 0;
-            out[i] = 0;
-            out[i + 1] = 0;
-            out[i + 2] = 0;
-            out[i + 3] = 255;
-        }
-    }
-    else {
-        const targetY = ch - 1;
-        for (let x = 0; x < cw; x++) {
-            const i = ((targetY * newWidth + x) * 4) | 0;
-            out[i] = 0;
-            out[i + 1] = 0;
-            out[i + 2] = 0;
-            out[i + 3] = 255;
-        }
+    const targetY = ch - 1;
+    for (let x = 0; x < cw; x++) {
+        const i = ((targetY * newWidth + x) * 4) | 0;
+        out[i] = 0;
+        out[i + 1] = 0;
+        out[i + 2] = 0;
+        out[i + 3] = 255;
     }
     const lastY = ch;
     for (let x = 0; x < newWidth; x++) {
@@ -341,11 +360,32 @@ export async function cropAndReconstitute(input) {
             finalOut[i + 3] = line[x][3] === 0 ? 255 : line[x][3];
         }
     }
-    return sharp(finalOut, {
+    if (finalHeight >= 2) {
+        const secondLastY = finalHeight - 2;
+        for (let x = 0; x < finalWidth; x++) {
+            const i = ((secondLastY * finalWidth + x) * 4) | 0;
+            const r = finalOut[i];
+            const g = finalOut[i + 1];
+            const b = finalOut[i + 2];
+            if ((r === 255 && g === 0 && b === 0) ||
+                (r === 0 && g === 255 && b === 0) ||
+                (r === 0 && g === 0 && b === 255)) {
+                finalOut[i] = 0;
+                finalOut[i + 1] = 0;
+                finalOut[i + 2] = 0;
+                finalOut[i + 3] = 255;
+            }
+        }
+    }
+    const resultBuffer = await sharp(finalOut, {
         raw: { width: finalWidth, height: finalHeight, channels: 4 },
     })
         .png()
         .toBuffer();
+    if (debugDir) {
+        await sharp(resultBuffer).toFile(join(debugDir, 'reconstructed.png'));
+    }
+    return resultBuffer;
 }
 /**
  * Encode a Buffer into a PNG wrapper. Supports optional compression and
@@ -359,14 +399,8 @@ export async function encodeBinaryToPng(input, opts = {}) {
     let payload = Buffer.concat([MAGIC, input]);
     const brQuality = typeof opts.brQuality === 'number' ? opts.brQuality : 11;
     const mode = opts.mode === undefined ? 'screenshot' : opts.mode;
-    const useBrotli = opts.compression === 'br' ||
-        (opts.compression === undefined &&
-            (mode === 'compact' || mode === 'pixel' || mode === 'screenshot'));
-    if (useBrotli) {
-        payload = zlib.brotliCompressSync(payload, {
-            params: { [zlib.constants.BROTLI_PARAM_QUALITY]: brQuality },
-        });
-    }
+    const compression = opts.compression || 'zstd';
+    payload = Buffer.from(await zstdCompress(payload, 22));
     if (opts.passphrase && !opts.encrypt) {
         opts.encrypt = 'aes';
     }
@@ -443,9 +477,14 @@ export async function encodeBinaryToPng(input, opts = {}) {
             ? Buffer.concat([dataWithoutMarkers, Buffer.alloc(padding)])
             : dataWithoutMarkers;
         const markerStartBytes = colorsToBytes(MARKER_START);
-        const dataWithMarkerStart = Buffer.concat([markerStartBytes, paddedData]);
+        const compressionMarkerBytes = colorsToBytes(COMPRESSION_MARKERS.zstd);
+        const dataWithMarkers = Buffer.concat([
+            markerStartBytes,
+            compressionMarkerBytes,
+            paddedData,
+        ]);
         const bytesPerPixel = 3;
-        const dataPixels = Math.ceil(dataWithMarkerStart.length / 3);
+        const dataPixels = Math.ceil(dataWithMarkers.length / 3);
         let logicalWidth = Math.ceil(Math.sqrt(dataPixels));
         if (logicalWidth < MARKER_END.length) {
             logicalWidth = MARKER_END.length;
@@ -455,7 +494,7 @@ export async function encodeBinaryToPng(input, opts = {}) {
         const spaceInLastRow = pixelsInLastRow === 0 ? logicalWidth : logicalWidth - pixelsInLastRow;
         const needsExtraRow = spaceInLastRow < MARKER_END.length;
         const logicalHeight = needsExtraRow ? dataRows + 1 : dataRows;
-        const scale = 2;
+        const scale = 1;
         const width = logicalWidth * scale;
         const height = logicalHeight * scale;
         const raw = Buffer.alloc(width * height * bytesPerPixel);
@@ -473,17 +512,14 @@ export async function encodeBinaryToPng(input, opts = {}) {
                 else if (ly < dataRows ||
                     (ly === dataRows && linearIdx < dataPixels)) {
                     const srcIdx = linearIdx * 3;
-                    r =
-                        srcIdx < dataWithMarkerStart.length
-                            ? dataWithMarkerStart[srcIdx]
-                            : 0;
+                    r = srcIdx < dataWithMarkers.length ? dataWithMarkers[srcIdx] : 0;
                     g =
-                        srcIdx + 1 < dataWithMarkerStart.length
-                            ? dataWithMarkerStart[srcIdx + 1]
+                        srcIdx + 1 < dataWithMarkers.length
+                            ? dataWithMarkers[srcIdx + 1]
                             : 0;
                     b =
-                        srcIdx + 2 < dataWithMarkerStart.length
-                            ? dataWithMarkerStart[srcIdx + 2]
+                        srcIdx + 2 < dataWithMarkers.length
+                            ? dataWithMarkers[srcIdx + 2]
                             : 0;
                 }
                 for (let sy = 0; sy < scale; sy++) {
@@ -628,13 +664,13 @@ export async function decodePngToBinary(pngBuf, opts = {}) {
         const rawPayload = d.slice(idx);
         let payload = tryDecryptIfNeeded(rawPayload, opts.passphrase);
         try {
-            payload = tryBrotliDecompress(payload);
+            payload = await tryZstdDecompress(payload);
         }
         catch (e) {
             const errMsg = e instanceof Error ? e.message : String(e);
             if (opts.passphrase)
-                throw new Error('Incorrect passphrase (ROX format, brotli failed: ' + errMsg + ')');
-            throw new Error('ROX format brotli decompression failed: ' + errMsg);
+                throw new Error('Incorrect passphrase (ROX format, zstd failed: ' + errMsg + ')');
+            throw new Error('ROX format zstd decompression failed: ' + errMsg);
         }
         if (!payload.slice(0, MAGIC.length).equals(MAGIC)) {
             throw new Error('Invalid ROX format (ROX direct: missing ROX1 magic after decompression)');
@@ -682,13 +718,13 @@ export async function decodePngToBinary(pngBuf, opts = {}) {
             throw new DataFormatError('Compact mode payload empty');
         let payload = tryDecryptIfNeeded(rawPayload, opts.passphrase);
         try {
-            payload = tryBrotliDecompress(payload);
+            payload = await tryZstdDecompress(payload);
         }
         catch (e) {
             const errMsg = e instanceof Error ? e.message : String(e);
             if (opts.passphrase)
-                throw new IncorrectPassphraseError('Incorrect passphrase (compact mode, brotli failed: ' + errMsg + ')');
-            throw new DataFormatError('Compact mode brotli decompression failed: ' + errMsg);
+                throw new IncorrectPassphraseError('Incorrect passphrase (compact mode, zstd failed: ' + errMsg + ')');
+            throw new DataFormatError('Compact mode zstd decompression failed: ' + errMsg);
         }
         if (!payload.slice(0, MAGIC.length).equals(MAGIC)) {
             throw new DataFormatError('Invalid ROX format (compact mode: missing ROX1 magic after decompression)');
@@ -748,7 +784,7 @@ export async function decodePngToBinary(pngBuf, opts = {}) {
             logicalData = rawRGB;
         }
         else {
-            const reconstructed = await cropAndReconstitute(data);
+            const reconstructed = await cropAndReconstitute(data, opts.debugDir);
             const { data: rdata, info: rinfo } = await sharp(reconstructed)
                 .ensureAlpha()
                 .raw()
@@ -794,14 +830,9 @@ export async function decodePngToBinary(pngBuf, opts = {}) {
             const rawPayload = logicalData.slice(idx, idx + payloadLen);
             let payload = tryDecryptIfNeeded(rawPayload, opts.passphrase);
             try {
-                payload = tryBrotliDecompress(payload);
-            }
-            catch (e) {
-                const errMsg = e instanceof Error ? e.message : String(e);
-                if (opts.passphrase)
-                    throw new IncorrectPassphraseError('Incorrect passphrase (pixel mode, brotli failed: ' + errMsg + ')');
-                throw new DataFormatError('Pixel mode brotli decompression failed: ' + errMsg);
+                payload = await tryZstdDecompress(payload);
             }
+            catch (e) { }
             if (!payload.slice(0, MAGIC.length).equals(MAGIC)) {
                 throw new DataFormatError('Invalid ROX format (pixel mode: missing ROX1 magic after decompression)');
             }
@@ -931,6 +962,19 @@ export async function decodePngToBinary(pngBuf, opts = {}) {
                 throw new Error('Marker START not found - image format not supported');
             }
         }
+        let compression = 'zstd';
+        if (gridFromStart.length > MARKER_START.length) {
+            const compPixel = gridFromStart[MARKER_START.length];
+            if (compPixel.r === 0 && compPixel.g === 255 && compPixel.b === 0) {
+                compression = 'zstd';
+            }
+            else {
+                compression = 'zstd';
+            }
+        }
+        if (process.env.ROX_DEBUG) {
+            console.log(`DEBUG: Detected compression: ${compression}`);
+        }
         let endStartIdx = -1;
         const lastLineStart = (logicalHeight - 1) * logicalWidth;
         const endMarkerStartCol = logicalWidth - MARKER_END.length;
@@ -966,7 +1010,7 @@ export async function decodePngToBinary(pngBuf, opts = {}) {
             }
             endStartIdx = gridFromStart.length;
         }
-        const dataGrid = gridFromStart.slice(MARKER_START.length, endStartIdx);
+        const dataGrid = gridFromStart.slice(MARKER_START.length + 1, endStartIdx);
         const pixelBytes = Buffer.alloc(dataGrid.length * 3);
         for (let i = 0; i < dataGrid.length; i++) {
             pixelBytes[i * 3] = dataGrid[i].r;
@@ -1015,15 +1059,15 @@ export async function decodePngToBinary(pngBuf, opts = {}) {
                 const rawPayload = pixelBytes.slice(idx, idx + payloadLen);
                 let payload = tryDecryptIfNeeded(rawPayload, opts.passphrase);
                 try {
-                    payload = tryBrotliDecompress(payload);
+                    payload = await tryZstdDecompress(payload);
                 }
                 catch (e) {
                     const errMsg = e instanceof Error ? e.message : String(e);
                     if (opts.passphrase)
-                        throw new IncorrectPassphraseError('Incorrect passphrase (pixel mode, brotli failed: ' +
+                        throw new IncorrectPassphraseError(`Incorrect passphrase (screenshot mode, zstd failed: ` +
                             errMsg +
                             ')');
-                    throw new DataFormatError('Pixel mode brotli decompression failed: ' + errMsg);
+                    throw new DataFormatError(`Screenshot mode zstd decompression failed: ` + errMsg);
                 }
                 if (!payload.slice(0, MAGIC.length).equals(MAGIC)) {
                     throw new DataFormatError('Invalid ROX format (pixel mode: missing ROX1 magic after decompression)');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "roxify",
-  "version": "1.1.1",
-  "description": "Encode binary data into PNG images and decode them back. Supports CLI and programmatic API (Node.js ESM).",
+  "version": "1.1.2",
+  "description": "Encode binary data into PNG images with Zstd compression and decode them back. Supports CLI and programmatic API (Node.js ESM).",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -40,6 +40,7 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@mongodb-js/zstd": "^7.0.0",
     "png-chunks-encode": "^1.0.0",
     "png-chunks-extract": "^1.0.0",
     "sharp": "^0.34.5"