roxify 1.1.6 → 1.1.8

package/README.md

@@ -28,8 +28,8 @@ npm install roxify
 
 ```bash
 npx rox encode <inputName>.ext (<outputName>.png)
-
 npx rox decode <inputName>.png (<outputName>.ext)
+npx rox list <inputName>.png
 ```
 
 If no output name is provided:
@@ -37,129 +37,70 @@ If no output name is provided:
 - Encoding: output defaults to `<inputName>.png`.
 - Decoding: if the image contains the original filename it will be restored; otherwise the output will be `decoded.bin`.
 
-**Commands:**
-
-- `encode <input>... [output]` — Encode file(s)/directory to PNG
-- `decode <input> [output]` — Decode PNG to file(s)
-- `list <input>` — List files in archive without decoding
-
 **Options:**
 
 - `-p, --passphrase <pass>` — Encrypt with AES-256-GCM
-- `-m, --mode <mode>` — Encoding mode: `screenshot` (default), `pixel`, `compact`, `chunk`
-- `-q, --quality <0-22>` — Roxify compression level (default: 22)
-- `--no-compress` — Disable compression
-- `--files <list>` — Extract only specified files (comma-separated, for archives)
 - `-v, --verbose` — Show detailed errors
 
 Run `npx rox help` for full options.
 
 ## API Usage
 
+### Basic Encoding and Decoding
+
 ```js
-import { encodeBinaryToPng, decodePngToBinary, listFilesInPng } from 'roxify';
+import { readFileSync, writeFileSync } from 'fs';
+import { encodeBinaryToPng } from 'roxify';
 
-// Encode a file
-const data = Buffer.from('Hello world');
-const png = await encodeBinaryToPng(data, {
-  mode: 'screenshot',
-  name: 'message.txt',
+const fileName = 'input.bin';
+const inputBuffer = readFileSync(fileName);
+const pngBuffer = await encodeBinaryToPng(inputBuffer, {
+  name: fileName,
 });
+writeFileSync('output.png', pngBuffer);
+```
 
-// Decode
-const { buf, meta } = await decodePngToBinary(png);
-console.log(buf.toString('utf8'));
-console.log(meta?.name);
-
-// List files in archive
-const files = listFilesInPng(png);
-console.log(files);
+```js
+import { readFileSync, writeFileSync } from 'fs';
+import { decodePngToBinary } from 'roxify';
 
-// Selective extraction
-const result = await decodePngToBinary(png, { files: ['file1.txt'] });
-if (result.files) {
-  // result.files contains only the selected files
-}
+const pngFromDisk = readFileSync('output.png');
+const { buf, meta } = await decodePngToBinary(pngFromDisk);
+writeFileSync(meta?.name ?? 'decoded.txt', buf);
 ```
 
-## Example: Progress Logging
+### With Passphrase
 
 ```js
-import { encodeBinaryToPng, decodePngToBinary } from 'roxify';
-
-const data = Buffer.from('Large data to encode...');
+const pngBuffer = await encodeBinaryToPng(inputBuffer, {
+  name: fileName,
+  passphrase: 'mysecret',
+});
+```
 
-// Encode with progress logging
-const png = await encodeBinaryToPng(data, {
-  onProgress: (info) => {
-    console.log(`Encoding phase: ${info.phase}`);
-    if (info.loaded && info.total) {
-      const percent = Math.round((info.loaded / info.total) * 100);
-      console.log(`Progress: ${percent}% (${info.loaded}/${info.total} bytes)`);
-    }
-  },
+```js
+const { buf, meta } = await decodePngToBinary(pngFromDisk, {
+  passphrase: 'mysecret',
 });
+```
+
+### With Progress Logging
 
-// Decode with progress logging
-const { buf } = await decodePngToBinary(png, {
+```js
+const pngBuffer = await encodeBinaryToPng(inputBuffer, {
+  name: fileName,
   onProgress: (info) => {
-    console.log(`Decoding phase: ${info.phase}`);
+    console.log(`Phase: ${info.phase}, Loaded: ${info.loaded}/${info.total}`);
   },
 });
 ```
 
-**API:**
-
-- `encodeBinaryToPng(input: Buffer, opts?: EncodeOptions): Promise<Buffer>`
-- `decodePngToBinary(pngBuf: Buffer, opts?: DecodeOptions): Promise<DecodeResult>`
-- `listFilesInPng(pngBuf: Buffer): string[] | null`
-
-**EncodeOptions:**
-
-- `mode` — `'screenshot'` | `'pixel'` | `'compact'` | `'chunk'` (default: `'screenshot'`)
-- `name` — Original filename (embedded as metadata)
-- `passphrase` — Encryption passphrase (uses AES-256-GCM)
-- `compression` — `'Roxify'` | `'none'` (default: `'Roxify'`)
-- `brQuality` — Roxify compression level 0-22 (default: 22)
-- `showProgress` — Display progress bar (default: `false`)
-- `onProgress` — Callback for progress updates: `(info: { phase: string; loaded?: number; total?: number }) => void`
-- `includeFileList` — Include file list for archives (default: `true` for directories)
-
-**DecodeOptions:**
-
-- `passphrase` — Decryption passphrase
-- `files` — List of files to extract selectively (for archives)
-- `showProgress` — Display progress bar (default: `false`)
-- `onProgress` — Callback for progress updates: `(info: { phase: string; loaded?: number; total?: number }) => void`
-
-**DecodeResult:**
-
-- `buf?: Buffer` — Decoded data (if not selective extraction)
-- `files?: PackedFile[]` — Extracted files (if selective extraction)
-- `meta?: { name?: string }` — Metadata
-
-## Example: Archive with Selective Extraction
-
 ```js
-import { encodeBinaryToPng, decodePngToBinary, listFilesInPng } from 'roxify';
-
-// Pack a directory
-const fs = require('fs');
-const dirData = packPaths(['myfolder']); // From pack.js
-const png = await encodeBinaryToPng(dirData.buf, {
-  includeFileList: true,
-  fileList: dirData.list,
+const { buf, meta } = await decodePngToBinary(pngFromDisk, {
+  onProgress: (info) => {
+    console.log(`Phase: ${info.phase}, Loaded: ${info.loaded}/${info.total}`);
+  },
 });
-
-// List files without decoding
-const files = listFilesInPng(png);
-console.log('Files:', files);
-
-// Extract only one file
-const result = await decodePngToBinary(png, { files: ['myfolder/file.txt'] });
-if (result.files) {
-  fs.writeFileSync('extracted.txt', result.files[0].buf);
-}
 ```
 
 ## Requirements

package/dist/cli.js

@@ -4,7 +4,7 @@ import { mkdirSync, readFileSync, statSync, writeFileSync } from 'fs';
 import { basename, dirname, join, resolve } from 'path';
 import { DataFormatError, decodePngToBinary, encodeBinaryToPng, IncorrectPassphraseError, listFilesInPng, PassphraseRequiredError, } from './index.js';
 import { packPaths, unpackBuffer } from './pack.js';
-const VERSION = '1.1.5';
+const VERSION = '1.1.7';
 function showHelp() {
     console.log(`
 ROX CLI — Encode/decode binary in PNG
@@ -133,11 +133,14 @@ async function encodeCommand(args) {
         process.exit(1);
     }
     const resolvedInputs = inputPaths.map((p) => resolve(p));
-    const resolvedOutput = parsed.output ||
-        outputPath ||
-        (inputPaths.length === 1
-            ? firstInput.replace(/(\.[^.]+)?$/, '.png')
-            : 'archive.png');
+    let outputName = inputPaths.length === 1 ? basename(firstInput) : 'archive';
+    if (inputPaths.length === 1 && !statSync(resolvedInputs[0]).isDirectory()) {
+        outputName = outputName.replace(/(\.[^.]+)?$/, '.png');
+    }
+    else {
+        outputName += '.png';
+    }
+    const resolvedOutput = parsed.output || outputPath || outputName;
     let options = {};
     try {
         let inputBuffer;
@@ -174,13 +177,10 @@ async function encodeCommand(args) {
         }
         else {
             const resolvedInput = resolvedInputs[0];
-            console.log(' ');
-            console.log(`Reading: ${resolvedInput}`);
-            console.log(' ');
             const st = statSync(resolvedInput);
             if (st.isDirectory()) {
                 console.log(`Packing directory...`);
-                const packResult = packPaths([resolvedInput]);
+                const packResult = packPaths([resolvedInput], resolvedInput);
                 inputBuffer = packResult.buf;
                 console.log(`Packed ${packResult.list.length} files -> ${(inputBuffer.length /
                     1024 /
@@ -219,30 +219,59 @@ async function encodeCommand(args) {
             elapsed: '0',
         });
         const startEncode = Date.now();
+        let currentEncodePct = 0;
+        let currentEncodeStep = 'Starting';
+        const encodeHeartbeat = setInterval(() => {
+            encodeBar.update(Math.floor(currentEncodePct), {
+                step: currentEncodeStep,
+                elapsed: String(Math.floor((Date.now() - startEncode) / 1000)),
+            });
+        }, 1000);
         options.onProgress = (info) => {
             let pct = 0;
-            if (info.phase === 'compress_progress') {
-                pct = (info.loaded / info.total) * 50;
+            let stepLabel = 'Processing';
+            if (info.phase === 'compress_start') {
+                pct = 5;
+                stepLabel = 'Compressing';
+            }
+            else if (info.phase === 'compress_progress') {
+                pct = 5 + Math.floor((info.loaded / info.total) * 45);
+                stepLabel = 'Compressing';
             }
             else if (info.phase === 'compress_done') {
                 pct = 50;
+                stepLabel = 'Compressed';
+            }
+            else if (info.phase === 'encrypt_start') {
+                pct = 60;
+                stepLabel = 'Encrypting';
             }
             else if (info.phase === 'encrypt_done') {
+                pct = 75;
+                stepLabel = 'Encrypted';
+            }
+            else if (info.phase === 'meta_prep_done') {
                 pct = 80;
+                stepLabel = 'Preparing';
             }
             else if (info.phase === 'png_gen') {
                 pct = 90;
+                stepLabel = 'Generating PNG';
             }
             else if (info.phase === 'done') {
                 pct = 100;
+                stepLabel = 'Done';
             }
+            currentEncodePct = pct;
+            currentEncodeStep = stepLabel;
             encodeBar.update(Math.floor(pct), {
-                step: info.phase.replace('_', ' '),
+                step: stepLabel,
                 elapsed: String(Math.floor((Date.now() - startEncode) / 1000)),
             });
         };
         const output = await encodeBinaryToPng(inputBuffer, options);
         const encodeTime = Date.now() - startEncode;
+        clearInterval(encodeHeartbeat);
         encodeBar.update(100, {
             step: 'done',
             elapsed: String(Math.floor(encodeTime / 1000)),
@@ -277,10 +306,8 @@ async function decodeCommand(args) {
         process.exit(1);
     }
     const resolvedInput = resolve(inputPath);
+    const resolvedOutput = parsed.output || outputPath || 'decoded.bin';
     try {
-        const inputBuffer = readFileSync(resolvedInput);
-        console.log(' ');
-        console.log(`Reading: ${resolvedInput}`);
         const options = {};
         if (parsed.passphrase) {
             options.passphrase = parsed.passphrase;
@@ -292,7 +319,6 @@ async function decodeCommand(args) {
             options.files = parsed.files;
         }
         console.log(' ');
-        console.log(' ');
         console.log(`Decoding...`);
         console.log(' ');
         const decodeBar = new cliProgress.SingleBar({
@@ -303,17 +329,42 @@ async function decodeCommand(args) {
             elapsed: '0',
         });
         const startDecode = Date.now();
+        let currentPct = 50;
+        let currentStep = 'Decoding';
+        const heartbeat = setInterval(() => {
+            decodeBar.update(Math.floor(currentPct), {
+                step: currentStep,
+                elapsed: String(Math.floor((Date.now() - startDecode) / 1000)),
+            });
+        }, 1000);
         options.onProgress = (info) => {
-            let pct = 50;
-            if (info.phase === 'done')
-                pct = 100;
-            decodeBar.update(pct, {
-                step: 'Decoding',
+            if (info.phase === 'decompress_start') {
+                currentPct = 50;
+                currentStep = 'Decompressing';
+            }
+            else if (info.phase === 'decompress_progress' &&
+                info.loaded &&
+                info.total) {
+                currentPct = 50 + Math.floor((info.loaded / info.total) * 40);
+                currentStep = `Decompressing (${info.loaded}/${info.total})`;
+            }
+            else if (info.phase === 'decompress_done') {
+                currentPct = 90;
+                currentStep = 'Decompressed';
+            }
+            else if (info.phase === 'done') {
+                currentPct = 100;
+                currentStep = 'Done';
+            }
+            decodeBar.update(Math.floor(currentPct), {
+                step: currentStep,
                 elapsed: String(Math.floor((Date.now() - startDecode) / 1000)),
             });
         };
+        const inputBuffer = readFileSync(resolvedInput);
         const result = await decodePngToBinary(inputBuffer, options);
         const decodeTime = Date.now() - startDecode;
+        clearInterval(heartbeat);
         decodeBar.update(100, {
             step: 'done',
             elapsed: String(Math.floor(decodeTime / 1000)),
@@ -328,33 +379,43 @@ async function decodeCommand(args) {
                 writeFileSync(fullPath, file.buf);
             }
             console.log(`\nSuccess!`);
-            console.log(`Extracted ${result.files.length} files to ${baseDir === '.' ? 'current directory' : baseDir}`);
+            console.log(`Unpacked ${result.files.length} files to directory : ${resolve(baseDir)}`);
             console.log(`Time: ${decodeTime}ms`);
         }
         else if (result.buf) {
             const unpacked = unpackBuffer(result.buf);
             if (unpacked) {
-                const baseDir = parsed.output || outputPath || result.meta?.name || '.';
+                const baseDir = parsed.output || outputPath || '.';
                 for (const file of unpacked.files) {
                     const fullPath = join(baseDir, file.path);
                     const dir = dirname(fullPath);
                     mkdirSync(dir, { recursive: true });
                     writeFileSync(fullPath, file.buf);
                 }
-                console.log(`Unpacked ${unpacked.files.length} files to ${baseDir === '.' ? 'current directory' : baseDir}`);
+                console.log(`\nSuccess!`);
+                console.log(`Time: ${decodeTime}ms`);
+                console.log(`Unpacked ${unpacked.files.length} files to current directory`);
             }
             else {
-                const resolvedOutput = parsed.output || outputPath || result.meta?.name || 'decoded.bin';
-                writeFileSync(resolvedOutput, result.buf);
+                let finalOutput = resolvedOutput;
+                if (!parsed.output && !outputPath && result.meta?.name) {
+                    finalOutput = result.meta.name;
+                }
+                writeFileSync(finalOutput, result.buf);
                 console.log(`\nSuccess!`);
                 if (result.meta?.name) {
                     console.log(`  Original name: ${result.meta.name}`);
                 }
-                console.log(`  Output size:   ${(result.buf.length / 1024 / 1024).toFixed(2)} MB`);
+                const outputSize = (result.buf.length / 1024 / 1024).toFixed(2);
+                console.log(`  Output size:   ${outputSize} MB`);
                 console.log(`  Time:          ${decodeTime}ms`);
-                console.log(`  Saved:         ${resolvedOutput}`);
+                console.log(`  Saved:         ${finalOutput}`);
             }
         }
+        else {
+            console.log(`\nSuccess!`);
+            console.log(`Time: ${decodeTime}ms`);
+        }
         console.log(' ');
     }
     catch (err) {

package/dist/index.d.ts

@@ -127,6 +127,10 @@ export interface DecodeOptions {
      * Directory to save debug images (doubled.png, reconstructed.png).
      */
     debugDir?: string;
+    /**
+     * Path to write decoded output directly to disk (streamed) to avoid high memory usage.
+     */
+    outPath?: string;
     /**
      * List of files to extract selectively from archives.
      */
@@ -153,6 +157,19 @@ export declare function cropAndReconstitute(input: Buffer, debugDir?: string): P
  * @param input - Data to encode
  * @param opts - Encoding options
  * @public
+ * @example
+ * ```typescript
+* import { readFileSync, writeFileSync } from 'fs';
+* import { encodeBinaryToPng } from 'roxify';
+*
+* const fileName = 'input.bin'; //Path of your input file here
+* const inputBuffer = readFileSync(fileName);
+* const pngBuffer = await encodeBinaryToPng(inputBuffer, {
+*   name: fileName,
+* });
+* writeFileSync('output.png', pngBuffer);
+
+ * ```
  */
 export declare function encodeBinaryToPng(input: Buffer, opts?: EncodeOptions): Promise<Buffer>;
 /**
@@ -162,6 +179,13 @@ export declare function encodeBinaryToPng(input: Buffer, opts?: EncodeOptions):
  * @param pngBuf - PNG data
  * @param opts - Options (passphrase for encrypted inputs)
  * @public
+ * @example
+ * import { readFileSync, writeFileSync } from 'fs';
+ * import { decodePngToBinary } from 'roxify';
+ *
+ * const pngFromDisk = readFileSync('output.png'); //Path of the encoded PNG here
+ * const { buf, meta } = await decodePngToBinary(pngFromDisk);
+ * writeFileSync(meta?.name ?? 'decoded.txt', buf);
  */
 export declare function decodePngToBinary(pngBuf: Buffer, opts?: DecodeOptions): Promise<DecodeResult>;
 export { packPaths, unpackBuffer } from './pack.js';

package/dist/index.js

@@ -1,6 +1,8 @@
 import { compress as zstdCompress, decompress as zstdDecompress, } from '@mongodb-js/zstd';
 import cliProgress from 'cli-progress';
 import { createCipheriv, createDecipheriv, pbkdf2Sync, randomBytes, } from 'crypto';
+import { createReadStream, createWriteStream, readFileSync, unlinkSync, } from 'fs';
+import { tmpdir } from 'os';
 import { join } from 'path';
 import encode from 'png-chunks-encode';
 import extract from 'png-chunks-extract';
@@ -42,6 +44,15 @@ const MARKER_COLORS = [
 ];
 const MARKER_START = MARKER_COLORS;
 const MARKER_END = [...MARKER_COLORS].reverse();
+const CHUNK_SIZE = 8 * 1024;
+async function writeInChunks(ws, buf, chunkSize = CHUNK_SIZE) {
+    for (let i = 0; i < buf.length; i += chunkSize) {
+        const part = buf.slice(i, i + chunkSize);
+        if (!ws.write(part))
+            await new Promise((resolve) => ws.once('drain', resolve));
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+}
 const COMPRESSION_MARKERS = {
     zstd: [{ r: 0, g: 255, b: 0 }],
 };
@@ -54,6 +65,144 @@ function colorsToBytes(colors) {
     }
     return buf;
 }
+function deltaEncode(data) {
+    if (data.length === 0)
+        return data;
+    const out = Buffer.alloc(data.length);
+    out[0] = data[0];
+    for (let i = 1; i < data.length; i++) {
+        out[i] = (data[i] - data[i - 1] + 256) & 0xff;
+    }
+    return out;
+}
+function deltaDecode(data) {
+    if (data.length === 0)
+        return data;
+    const out = Buffer.alloc(data.length);
+    out[0] = data[0];
+    for (let i = 1; i < data.length; i++) {
+        out[i] = (out[i - 1] + data[i]) & 0xff;
+    }
+    return out;
+}
+async function parallelZstdCompress(payload, level = 22, onProgress) {
+    const chunkSize = 1024 * 1024 * 1024;
+    if (payload.length <= chunkSize) {
+        return Buffer.from(await zstdCompress(payload, level));
+    }
+    const chunks = [];
+    const promises = [];
+    const totalChunks = Math.ceil(payload.length / chunkSize);
+    let completedChunks = 0;
+    for (let i = 0; i < payload.length; i += chunkSize) {
+        const chunk = payload.slice(i, Math.min(i + chunkSize, payload.length));
+        promises.push(zstdCompress(chunk, level).then((compressed) => {
+            completedChunks++;
+            if (onProgress) {
+                onProgress(completedChunks, totalChunks);
+            }
+            return Buffer.from(compressed);
+        }));
+    }
+    const compressedChunks = await Promise.all(promises);
+    const chunkSizes = Buffer.alloc(compressedChunks.length * 4);
+    for (let i = 0; i < compressedChunks.length; i++) {
+        chunkSizes.writeUInt32BE(compressedChunks[i].length, i * 4);
+    }
+    const header = Buffer.alloc(8);
+    header.writeUInt32BE(0x5a535444, 0);
+    header.writeUInt32BE(compressedChunks.length, 4);
+    return Buffer.concat([header, chunkSizes, ...compressedChunks]);
+}
+async function parallelZstdDecompress(payload, onProgress, onChunk, outPath) {
+    if (payload.length < 8) {
+        onProgress?.({ phase: 'decompress_start', total: 1 });
+        const d = Buffer.from(await zstdDecompress(payload));
+        if (onChunk)
+            await onChunk(d, 0, 1);
+        onProgress?.({ phase: 'decompress_progress', loaded: 1, total: 1 });
+        onProgress?.({ phase: 'decompress_done', loaded: 1, total: 1 });
+        if (outPath) {
+            const ws = createWriteStream(outPath);
+            await writeInChunks(ws, d);
+            ws.end();
+        }
+        return onChunk ? Buffer.alloc(0) : d;
+    }
+    const magic = payload.readUInt32BE(0);
+    if (magic !== 0x5a535444) {
+        onProgress?.({ phase: 'decompress_start', total: 1 });
+        const d = Buffer.from(await zstdDecompress(payload));
+        onProgress?.({ phase: 'decompress_progress', loaded: 1, total: 1 });
+        onProgress?.({ phase: 'decompress_done', loaded: 1, total: 1 });
+        if (outPath) {
+            const ws = createWriteStream(outPath);
+            await writeInChunks(ws, d);
+            ws.end();
+        }
+        return d;
+    }
+    const numChunks = payload.readUInt32BE(4);
+    const chunkSizes = [];
+    let offset = 8;
+    for (let i = 0; i < numChunks; i++) {
+        chunkSizes.push(payload.readUInt32BE(offset));
+        offset += 4;
+    }
+    onProgress?.({ phase: 'decompress_start', total: numChunks });
+    const tempFiles = [];
+    for (let i = 0; i < numChunks; i++) {
+        const size = chunkSizes[i];
+        const chunk = payload.slice(offset, offset + size);
+        offset += size;
+        const tempFile = join(tmpdir(), `rox_chunk_${Date.now()}_${i}.tmp`);
+        const wsChunk = createWriteStream(tempFile);
+        const dec = Buffer.from(await zstdDecompress(chunk));
+        if (onChunk) {
+            await onChunk(dec, i + 1, numChunks);
+            unlinkSync(tempFile);
+        }
+        else {
+            await writeInChunks(wsChunk, dec);
+            await new Promise((res) => wsChunk.end(() => res()));
+            tempFiles.push(tempFile);
+        }
+        onProgress?.({
+            phase: 'decompress_progress',
+            loaded: i + 1,
+            total: numChunks,
+        });
+    }
+    onProgress?.({
+        phase: 'decompress_done',
+        loaded: numChunks,
+        total: numChunks,
+    });
+    if (onChunk) {
+        return Buffer.alloc(0);
+    }
+    if (outPath || tempFiles.length > 0) {
+        const finalPath = outPath || join(tmpdir(), `rox_final_${Date.now()}.tmp`);
+        const ws = createWriteStream(finalPath);
+        for (const tempFile of tempFiles) {
+            const rs = createReadStream(tempFile);
+            await new Promise((resolve, reject) => {
+                rs.on('data', (chunk) => ws.write(chunk));
+                rs.on('end', resolve);
+                rs.on('error', reject);
+            });
+            unlinkSync(tempFile);
+        }
+        await new Promise((res) => ws.end(() => res()));
+        if (!outPath) {
+            const finalBuf = readFileSync(finalPath);
+            unlinkSync(finalPath);
+            return finalBuf;
+        }
+        return Buffer.alloc(0);
+    }
+    return Buffer.alloc(0);
+}
 function applyXor(buf, passphrase) {
     const key = Buffer.from(passphrase, 'utf8');
     const out = Buffer.alloc(buf.length);
@@ -65,14 +214,8 @@ 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;
-    }
+async function tryZstdDecompress(payload, onProgress, onChunk, outPath) {
+    return await parallelZstdDecompress(payload, onProgress, onChunk, outPath);
 }
 function tryDecryptIfNeeded(buf, passphrase) {
     if (!buf || buf.length === 0)
@@ -394,6 +537,19 @@ export async function cropAndReconstitute(input, debugDir) {
  * @param input - Data to encode
  * @param opts - Encoding options
  * @public
+ * @example
+ * ```typescript
+* import { readFileSync, writeFileSync } from 'fs';
+* import { encodeBinaryToPng } from 'roxify';
+*
+* const fileName = 'input.bin'; //Path of your input file here
+* const inputBuffer = readFileSync(fileName);
+* const pngBuffer = await encodeBinaryToPng(inputBuffer, {
+*   name: fileName,
+* });
+* writeFileSync('output.png', pngBuffer);
+
+ * ```
  */
 export async function encodeBinaryToPng(input, opts = {}) {
     let progressBar = null;
@@ -434,20 +590,17 @@ export async function encodeBinaryToPng(input, opts = {}) {
     const compression = opts.compression || 'zstd';
     if (opts.onProgress)
         opts.onProgress({ phase: 'compress_start', total: payload.length });
-    const compressedChunks = [];
-    const chunkSize = 1024 * 1024;
-    for (let i = 0; i < payload.length; i += chunkSize) {
-        const chunk = payload.slice(i, Math.min(i + chunkSize, payload.length));
-        const compressedChunk = Buffer.from(await zstdCompress(chunk, 22));
-        compressedChunks.push(compressedChunk);
-        if (opts.onProgress)
+    const useDelta = mode !== 'screenshot';
+    const deltaEncoded = useDelta ? deltaEncode(payload) : payload;
+    payload = await parallelZstdCompress(deltaEncoded, 1, (loaded, total) => {
+        if (opts.onProgress) {
             opts.onProgress({
                 phase: 'compress_progress',
-                loaded: i + chunk.length,
-                total: payload.length,
+                loaded,
+                total,
             });
-    }
-    payload = Buffer.concat(compressedChunks);
+        }
+    });
     if (opts.onProgress)
         opts.onProgress({ phase: 'compress_done', loaded: payload.length });
     if (opts.passphrase && !opts.encrypt) {
@@ -480,6 +633,8 @@ export async function encodeBinaryToPng(input, opts = {}) {
             const enc = Buffer.concat([cipher.update(payload), cipher.final()]);
             const tag = cipher.getAuthTag();
             payload = Buffer.concat([Buffer.from([ENC_AES]), salt, iv, tag, enc]);
+            if (opts.onProgress)
+                opts.onProgress({ phase: 'encrypt_done' });
         }
         else if (encChoice === 'xor') {
             const xored = applyXor(payload, opts.passphrase);
@@ -520,7 +675,7 @@ export async function encodeBinaryToPng(input, opts = {}) {
         const nameLen = nameBuf.length;
         const payloadLenBuf = Buffer.alloc(4);
         payloadLenBuf.writeUInt32BE(payload.length, 0);
-        const version = 2;
+        const version = 1;
         const metaPixel = Buffer.concat([
             Buffer.from([version]),
             Buffer.from([nameLen]),
@@ -542,15 +697,21 @@ export async function encodeBinaryToPng(input, opts = {}) {
         ]);
         const bytesPerPixel = 3;
         const dataPixels = Math.ceil(dataWithMarkers.length / 3);
-        let logicalWidth = Math.ceil(Math.sqrt(dataPixels));
-        if (logicalWidth < MARKER_END.length) {
-            logicalWidth = MARKER_END.length;
-        }
-        const dataRows = Math.ceil(dataPixels / logicalWidth);
-        const pixelsInLastRow = dataPixels % logicalWidth;
-        const spaceInLastRow = pixelsInLastRow === 0 ? logicalWidth : logicalWidth - pixelsInLastRow;
-        const needsExtraRow = spaceInLastRow < MARKER_END.length;
-        const logicalHeight = needsExtraRow ? dataRows + 1 : dataRows;
+        const totalPixels = dataPixels + MARKER_END.length;
+        const maxWidth = 16384;
+        let side = Math.ceil(Math.sqrt(totalPixels));
+        if (side < MARKER_END.length)
+            side = MARKER_END.length;
+        let logicalWidth;
+        let logicalHeight;
+        if (side <= maxWidth) {
+            logicalWidth = side;
+            logicalHeight = side;
+        }
+        else {
+            logicalWidth = Math.min(maxWidth, totalPixels);
+            logicalHeight = Math.ceil(totalPixels / logicalWidth);
+        }
         const scale = 1;
         const width = logicalWidth * scale;
         const height = logicalHeight * scale;
@@ -566,8 +727,7 @@ export async function encodeBinaryToPng(input, opts = {}) {
                     g = MARKER_END[markerIdx].g;
                     b = MARKER_END[markerIdx].b;
                 }
-                else if (ly < dataRows ||
-                    (ly === dataRows && linearIdx < dataPixels)) {
+                else if (linearIdx < dataPixels) {
                     const srcIdx = linearIdx * 3;
                     r = srcIdx < dataWithMarkers.length ? dataWithMarkers[srcIdx] : 0;
                     g =
@@ -593,7 +753,9 @@ export async function encodeBinaryToPng(input, opts = {}) {
         }
         if (opts.onProgress)
             opts.onProgress({ phase: 'png_gen' });
-        let bufScr = await sharp(raw, { raw: { width, height, channels: 3 } })
+        let bufScr = await sharp(raw, {
+            raw: { width, height, channels: 3 },
+        })
             .png({
             compressionLevel: 9,
             palette: false,
@@ -633,9 +795,10 @@ export async function encodeBinaryToPng(input, opts = {}) {
         const full = Buffer.concat([PIXEL_MAGIC, metaPixel]);
         const bytesPerPixel = 3;
         const nPixels = Math.ceil((full.length + 8) / 3);
-        const side = Math.ceil(Math.sqrt(nPixels));
-        const width = Math.max(1, Math.min(side, 65535));
-        const height = Math.ceil(nPixels / width);
+        const desiredSide = Math.ceil(Math.sqrt(nPixels));
+        const sideClamped = Math.max(1, Math.min(desiredSide, 65535));
+        const width = sideClamped;
+        const height = sideClamped === desiredSide ? sideClamped : Math.ceil(nPixels / width);
         const dimHeader = Buffer.alloc(8);
         dimHeader.writeUInt32BE(width, 0);
         dimHeader.writeUInt32BE(height, 4);
@@ -737,6 +900,13 @@ export async function encodeBinaryToPng(input, opts = {}) {
  * @param pngBuf - PNG data
  * @param opts - Options (passphrase for encrypted inputs)
  * @public
+ * @example
+ * import { readFileSync, writeFileSync } from 'fs';
+ * import { decodePngToBinary } from 'roxify';
+ *
+ * const pngFromDisk = readFileSync('output.png'); //Path of the encoded PNG here
+ * const { buf, meta } = await decodePngToBinary(pngFromDisk);
+ * writeFileSync(meta?.name ?? 'decoded.txt', buf);
  */
 export async function decodePngToBinary(pngBuf, opts = {}) {
     let progressBar = null;
@@ -771,15 +941,28 @@ export async function decodePngToBinary(pngBuf, opts = {}) {
     try {
         const info = await sharp(pngBuf).metadata();
         if (info.width && info.height) {
-            const doubledBuffer = await sharp(pngBuf)
-                .resize({
-                width: info.width * 2,
-                height: info.height * 2,
-                kernel: 'nearest',
-            })
-                .png()
-                .toBuffer();
-            processedBuf = await cropAndReconstitute(doubledBuffer, opts.debugDir);
+            const MAX_RAW_BYTES = 150 * 1024 * 1024;
+            const rawBytesEstimate = info.width * info.height * 4;
+            if (rawBytesEstimate > MAX_RAW_BYTES) {
+                throw new DataFormatError(`Image too large to decode in-process (${Math.round(rawBytesEstimate / 1024 / 1024)} MB). Increase Node heap or use a smaller image/compact mode.`);
+            }
+            const MAX_DOUBLE_BYTES = 200 * 1024 * 1024;
+            const doubledPixels = info.width * 2 * (info.height * 2);
+            const doubledBytesEstimate = doubledPixels * 4;
+            if (false) {
+                const doubledBuffer = await sharp(pngBuf)
+                    .resize({
+                    width: info.width * 2,
+                    height: info.height * 2,
+                    kernel: 'nearest',
+                })
+                    .png()
+                    .toBuffer();
+                processedBuf = await cropAndReconstitute(doubledBuffer, opts.debugDir);
+            }
+            else {
+                processedBuf = pngBuf;
+            }
         }
     }
     catch (e) { }
@@ -796,16 +979,54 @@ export async function decodePngToBinary(pngBuf, opts = {}) {
         }
         const rawPayload = d.slice(idx);
         let payload = tryDecryptIfNeeded(rawPayload, opts.passphrase);
+        if (opts.outPath) {
+            const ws = createWriteStream(opts.outPath, { highWaterMark: 64 * 1024 });
+            let headerBuf = Buffer.alloc(0);
+            let headerSkipped = false;
+            await tryZstdDecompress(payload, (info) => {
+                if (opts.onProgress)
+                    opts.onProgress(info);
+            }, async (decChunk) => {
+                if (!headerSkipped) {
+                    if (decChunk.length < MAGIC.length) {
+                        headerBuf = Buffer.concat([headerBuf, decChunk]);
+                        return;
+                    }
+                    const mag = decChunk.slice(0, MAGIC.length);
+                    if (!mag.equals(MAGIC)) {
+                        ws.close();
+                        throw new Error('Invalid ROX format (ROX direct: missing ROX1 magic after decompression)');
+                    }
+                    const toWriteBuf = decChunk.slice(MAGIC.length);
+                    if (toWriteBuf.length > 0) {
+                        await writeInChunks(ws, toWriteBuf, 16 * 1024);
+                    }
+                    headerBuf = Buffer.alloc(0);
+                    headerSkipped = true;
+                }
+                else {
+                    await writeInChunks(ws, decChunk, 64 * 1024);
+                }
+            });
+            await new Promise((res) => ws.end(() => res()));
+            if (opts.onProgress)
+                opts.onProgress({ phase: 'done' });
+            progressBar?.stop();
+            return { meta: { name } };
+        }
         if (opts.onProgress)
-            opts.onProgress({ phase: 'decompress' });
+            opts.onProgress({ phase: 'decompress_start' });
         try {
-            payload = await tryZstdDecompress(payload);
+            payload = await tryZstdDecompress(payload, (info) => {
+                if (opts.onProgress)
+                    opts.onProgress(info);
+            });
         }
         catch (e) {
             const errMsg = e instanceof Error ? e.message : String(e);
             if (opts.passphrase)
-                throw new Error('Incorrect passphrase (ROX format, zstd failed: ' + errMsg + ')');
-            throw new Error('ROX format zstd 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 Error('Invalid ROX format (ROX direct: missing ROX1 magic after decompression)');
@@ -855,10 +1076,48 @@ export async function decodePngToBinary(pngBuf, opts = {}) {
         if (rawPayload.length === 0)
             throw new DataFormatError('Compact mode payload empty');
         let payload = tryDecryptIfNeeded(rawPayload, opts.passphrase);
+        if (opts.outPath) {
+            const ws = createWriteStream(opts.outPath, { highWaterMark: 64 * 1024 });
+            let headerBuf = Buffer.alloc(0);
+            let headerSkipped = false;
+            await tryZstdDecompress(payload, (info) => {
+                if (opts.onProgress)
+                    opts.onProgress(info);
+            }, async (decChunk) => {
+                if (!headerSkipped) {
+                    if (decChunk.length < MAGIC.length) {
+                        headerBuf = Buffer.concat([headerBuf, decChunk]);
+                        return;
+                    }
+                    const mag = decChunk.slice(0, MAGIC.length);
+                    if (!mag.equals(MAGIC)) {
+                        ws.close();
+                        throw new DataFormatError('Invalid ROX format (compact mode: missing ROX1 magic after decompression)');
+                    }
+                    const toWriteBuf = decChunk.slice(MAGIC.length);
+                    if (toWriteBuf.length > 0) {
+                        await writeInChunks(ws, toWriteBuf);
+                    }
+                    headerBuf = Buffer.alloc(0);
+                    headerSkipped = true;
+                }
+                else {
+                    await writeInChunks(ws, decChunk, 64 * 1024);
+                }
+            });
+            await new Promise((res) => ws.end(() => res()));
+            if (opts.onProgress)
+                opts.onProgress({ phase: 'done' });
+            progressBar?.stop();
+            return { meta: { name } };
+        }
         if (opts.onProgress)
-            opts.onProgress({ phase: 'decompress' });
+            opts.onProgress({ phase: 'decompress_start' });
         try {
-            payload = await tryZstdDecompress(payload);
+            payload = await tryZstdDecompress(payload, (info) => {
+                if (opts.onProgress)
+                    opts.onProgress(info);
+            });
         }
         catch (e) {
             const errMsg = e instanceof Error ? e.message : String(e);
@@ -936,7 +1195,7 @@ export async function decodePngToBinary(pngBuf, opts = {}) {
             logicalData = rawRGB;
         }
         else {
-            const reconstructed = await cropAndReconstitute(data, opts.debugDir);
+            const reconstructed = await cropAndReconstitute(processedBuf, opts.debugDir);
             const { data: rdata, info: rinfo } = await sharp(reconstructed)
                 .ensureAlpha()
                 .raw()
@@ -982,7 +1241,26 @@ export async function decodePngToBinary(pngBuf, opts = {}) {
             const rawPayload = logicalData.slice(idx, idx + payloadLen);
             let payload = tryDecryptIfNeeded(rawPayload, opts.passphrase);
             try {
-                payload = await tryZstdDecompress(payload);
+                if (opts.outPath) {
+                    await tryZstdDecompress(payload, (info) => {
+                        if (opts.onProgress)
+                            opts.onProgress(info);
+                    }, undefined, opts.outPath);
+                }
+                else {
+                    payload = await tryZstdDecompress(payload, (info) => {
+                        if (opts.onProgress)
+                            opts.onProgress(info);
+                    });
+                }
+                if (version === 3) {
+                    if (opts.outPath) {
+                        throw new Error('outPath not supported with delta encoding yet');
+                    }
+                    else {
+                        payload = deltaDecode(payload);
+                    }
+                }
             }
             catch (e) { }
             if (!payload.slice(0, MAGIC.length).equals(MAGIC)) {
@@ -1211,7 +1489,70 @@ export async function decodePngToBinary(pngBuf, opts = {}) {
                 const rawPayload = pixelBytes.slice(idx, idx + payloadLen);
                 let payload = tryDecryptIfNeeded(rawPayload, opts.passphrase);
                 try {
-                    payload = await tryZstdDecompress(payload);
+                    if (opts.outPath) {
+                        const ws = createWriteStream(opts.outPath, {
+                            highWaterMark: 64 * 1024,
+                        });
+                        let headerBuf = Buffer.alloc(0);
+                        let headerSkipped = false;
+                        let lastOutByte = null;
+                        await tryZstdDecompress(payload, (info) => {
+                            if (opts.onProgress)
+                                opts.onProgress(info);
+                        }, async (decChunk, idxChunk, totalChunks) => {
+                            let outChunk = decChunk;
+                            if (version === 3) {
+                                const out = Buffer.alloc(decChunk.length);
+                                for (let i = 0; i < decChunk.length; i++) {
+                                    if (i === 0) {
+                                        out[0] =
+                                            typeof lastOutByte === 'number'
+                                                ? (lastOutByte + decChunk[0]) & 0xff
+                                                : decChunk[0];
+                                    }
+                                    else {
+                                        out[i] = (out[i - 1] + decChunk[i]) & 0xff;
+                                    }
+                                }
+                                lastOutByte = out[out.length - 1];
+                                outChunk = out;
+                            }
+                            if (!headerSkipped) {
+                                if (outChunk.length < MAGIC.length) {
+                                    headerBuf = Buffer.concat([headerBuf, outChunk]);
+                                    return;
+                                }
+                                const mag = outChunk.slice(0, MAGIC.length);
+                                if (!mag.equals(MAGIC)) {
+                                    ws.close();
+                                    throw new DataFormatError('Invalid ROX format (pixel mode: missing ROX1 magic after decompression)');
+                                }
+                                const toWriteBuf = outChunk.slice(MAGIC.length);
+                                if (toWriteBuf.length > 0) {
+                                    await writeInChunks(ws, toWriteBuf, 64 * 1024);
+                                }
+                                headerBuf = Buffer.alloc(0);
+                                headerSkipped = true;
+                            }
+                            else {
+                                await writeInChunks(ws, outChunk, 64 * 1024);
+                            }
+                        });
+                        await new Promise((res, rej) => ws.end(() => res()));
+                        if (opts.onProgress)
+                            opts.onProgress({ phase: 'done' });
+                        progressBar?.stop();
+                        return { meta: { name } };
+                    }
+                    else {
+                        payload = await tryZstdDecompress(payload, (info) => {
+                            if (opts.onProgress)
+                                opts.onProgress(info);
+                        });
+                        if (version === 3) {
+                            payload = deltaDecode(payload);
+                        }
+                    }
                 }
                 catch (e) {
                     const errMsg = e instanceof Error ? e.message : String(e);

package/dist/pack.d.ts

@@ -14,3 +14,13 @@ export declare function unpackBuffer(buf: Buffer, fileList?: string[]): {
         buf: Buffer;
     }[];
 } | null;
+/**
+ * Stream-unpack a packed buffer file on disk into a directory without
+ * loading the whole archive into memory.
+ */
+export declare function unpackFileToDir(filePath: string, baseDir: string, fileList?: string[]): {
+    files: {
+        path: string;
+        size: number;
+    }[];
+};

package/dist/pack.js

@@ -1,5 +1,5 @@
-import { readFileSync, readdirSync, statSync } from 'fs';
-import { join, relative, resolve, sep } from 'path';
+import { closeSync, createWriteStream, mkdirSync, openSync, readFileSync, readSync, readdirSync, statSync, } from 'fs';
+import { dirname, join, relative, resolve, sep } from 'path';
 function collectFiles(paths) {
     const files = [];
     for (const p of paths) {
@@ -83,3 +83,60 @@ export function unpackBuffer(buf, fileList) {
     }
     return { files };
 }
+/**
+ * Stream-unpack a packed buffer file on disk into a directory without
+ * loading the whole archive into memory.
+ */
+export function unpackFileToDir(filePath, baseDir, fileList) {
+    const fd = openSync(filePath, 'r');
+    try {
+        const headerBuf = Buffer.alloc(8);
+        let bytes = readSync(fd, headerBuf, 0, 8, 0);
+        if (bytes < 8)
+            throw new Error('Invalid archive');
+        if (headerBuf.readUInt32BE(0) !== 0x524f5850)
+            throw new Error('Not a pack archive');
+        const fileCount = headerBuf.readUInt32BE(4);
+        let offset = 8;
+        const files = [];
+        for (let i = 0; i < fileCount; i++) {
+            const nameLenBuf = Buffer.alloc(2);
+            readSync(fd, nameLenBuf, 0, 2, offset);
+            const nameLen = nameLenBuf.readUInt16BE(0);
+            offset += 2;
+            const nameBuf = Buffer.alloc(nameLen);
+            readSync(fd, nameBuf, 0, nameLen, offset);
+            const name = nameBuf.toString('utf8');
+            offset += nameLen;
+            const sizeBuf = Buffer.alloc(8);
+            readSync(fd, sizeBuf, 0, 8, offset);
+            const size = Number(sizeBuf.readBigUInt64BE(0));
+            offset += 8;
+            if (fileList && !fileList.includes(name)) {
+                offset += size;
+                continue;
+            }
+            const outPath = join(baseDir, name);
+            const outDir = dirname(outPath);
+            mkdirSync(outDir, { recursive: true });
+            const ws = createWriteStream(outPath);
+            let remaining = size;
+            const chunk = Buffer.alloc(64 * 1024);
+            while (remaining > 0) {
+                const toRead = Math.min(remaining, chunk.length);
+                const bytesRead = readSync(fd, chunk, 0, toRead, offset);
+                if (bytesRead <= 0)
+                    break;
+                ws.write(chunk.slice(0, bytesRead));
+                offset += bytesRead;
+                remaining -= bytesRead;
+            }
+            ws.end();
+            files.push({ path: name, size });
+        }
+        return { files };
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roxify",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "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",
@@ -16,21 +16,24 @@
     "build": "tsc",
     "check-publish": "node ../scripts/check-publish.js roxify",
     "cli": "node dist/cli.js",
-    "test": "node test/pack.test.js"
+    "test": "npm run build && node test/pack.test.js && node test/screenshot.test.js"
   },
   "keywords": [
     "steganography",
     "png",
-    "brotli",
-    "rox",
-    "compress",
-    "decompress",
+    "zstd",
+    "compression",
+    "encryption",
     "encode",
     "decode",
     "cli",
     "nodejs",
     "esm",
-    "qrcode"
+    "data-embedding",
+    "file-archive",
+    "lossless",
+    "aes-gcm",
+    "binary-data"
   ],
   "author": "RoxCompressor",
   "license": "UNLICENSED",