roxify 1.1.5 → 1.1.7

package/README.md

@@ -84,7 +84,7 @@ if (result.files) {
 
 ## Example: Progress Logging
 
-```js
+````js
 import { encodeBinaryToPng, decodePngToBinary } from 'roxify';
 
 const data = Buffer.from('Large data to encode...');
@@ -100,13 +100,37 @@ const png = await encodeBinaryToPng(data, {
   },
 });
 
+
+Node.js (detailed chunk progress example)
+
+```js
+import { encodeBinaryToPng } from 'roxify';
+import { readFileSync, writeFileSync } from 'fs';
+
+const buf = readFileSync('test-data/testVideo.mp4');
+const png = await encodeBinaryToPng(buf, {
+  showProgress: false,
+  onProgress(info) {
+    if (info.phase === 'compress_progress' && info.loaded && info.total) {
+      const percent = Math.round((info.loaded / info.total) * 100);
+      console.log(`[progress] ${info.phase} ${percent}% (${info.loaded}/${info.total} chunks)`);
+    } else {
+      console.log(`[progress] ${info.phase} ${info.loaded || ''}/${info.total || ''}`);
+    }
+  },
+});
+
+writeFileSync('out.png', png);
+````
+
 // Decode with progress logging
 const { buf } = await decodePngToBinary(png, {
-  onProgress: (info) => {
-    console.log(`Decoding phase: ${info.phase}`);
-  },
+onProgress: (info) => {
+console.log(`Decoding phase: ${info.phase}`);
+},
 });
-```
+
+````
 
 **API:**
 
@@ -160,7 +184,7 @@ 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
@@ -127,16 +127,20 @@ async function encodeCommand(args) {
             : undefined;
     const firstInput = inputPaths[0];
     if (!firstInput) {
+        console.log(' ');
         console.error('Error: Input file required');
         console.log('Usage: npx rox encode <input> [output] [options]');
         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;
@@ -173,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 /
@@ -218,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)),
@@ -259,6 +289,7 @@ async function encodeCommand(args) {
         console.log(' ');
     }
     catch (err) {
+        console.log(' ');
         console.error('Error: Failed to encode file. Use --verbose for details.');
         if (parsed.verbose)
             console.error('Details:', err.stack || err.message);
@@ -269,15 +300,14 @@ async function decodeCommand(args) {
     const parsed = parseArgs(args);
     const [inputPath, outputPath] = parsed._;
     if (!inputPath) {
+        console.log(' ');
         console.error('Error: Input PNG file required');
         console.log('Usage: npx rox decode <input> [output] [options]');
         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;
@@ -289,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({
@@ -300,24 +329,49 @@ 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)),
         });
         decodeBar.stop();
         if (result.files) {
-            const baseDir = parsed.output || outputPath || 'extracted';
+            const baseDir = parsed.output || outputPath || '.';
             for (const file of result.files) {
                 const fullPath = join(baseDir, file.path);
                 const dir = dirname(fullPath);
@@ -325,42 +379,54 @@ async function decodeCommand(args) {
                 writeFileSync(fullPath, file.buf);
             }
             console.log(`\nSuccess!`);
-            console.log(`Extracted ${result.files.length} files to ${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 || 'unpacked';
+                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}`);
+                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) {
         if (err instanceof PassphraseRequiredError ||
             (err.message && err.message.includes('passphrase') && !parsed.passphrase)) {
+            console.log(' ');
             console.error('File appears to be encrypted. Provide a passphrase with -p');
         }
         else if (err instanceof IncorrectPassphraseError ||
             (err.message && err.message.includes('Incorrect passphrase'))) {
+            console.log(' ');
             console.error('Incorrect passphrase');
         }
         else if (err instanceof DataFormatError ||
@@ -370,13 +436,16 @@ async function decodeCommand(args) {
                     err.message.includes('Pixel payload truncated') ||
                     err.message.includes('Marker START not found') ||
                     err.message.includes('Brotli decompression failed')))) {
+            console.log(' ');
             console.error('Data corrupted or unsupported format. Use --verbose for details.');
         }
         else {
+            console.log(' ');
             console.error('Failed to decode file. Use --verbose for details.');
         }
-        if (parsed.verbose)
+        if (parsed.verbose) {
             console.error('Details:', err.stack || err.message);
+        }
         process.exit(1);
     }
 }
@@ -384,6 +453,7 @@ async function listCommand(args) {
     const parsed = parseArgs(args);
     const [inputPath] = parsed._;
     if (!inputPath) {
+        console.log(' ');
         console.error('Error: Input PNG file required');
         console.log('Usage: npx rox list <input>');
         process.exit(1);
@@ -403,9 +473,11 @@ async function listCommand(args) {
         }
     }
     catch (err) {
+        console.log(' ');
         console.error('Failed to list files. Use --verbose for details.');
-        if (parsed.verbose)
+        if (parsed.verbose) {
             console.error('Details:', err.stack || err.message);
+        }
         process.exit(1);
     }
 }
@@ -438,6 +510,7 @@ async function main() {
     }
 }
 main().catch((err) => {
+    console.log(' ');
     console.error('Fatal error:', err);
     process.exit(1);
 });

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.
      */

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)
@@ -434,20 +577,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 +620,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 +662,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 +684,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 +714,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 +740,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 +782,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);
@@ -771,15 +921,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 +959,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 +1056,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 +1175,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 +1221,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 +1469,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);
@@ -1276,7 +1597,18 @@ export function listFilesInPng(pngBuf) {
             const data = Buffer.isBuffer(fileListChunk.data)
                 ? fileListChunk.data
                 : Buffer.from(fileListChunk.data);
-            return JSON.parse(data.toString('utf8'));
+            const files = JSON.parse(data.toString('utf8'));
+            const dirs = new Set();
+            for (const file of files) {
+                const parts = file.split('/');
+                let path = '';
+                for (let i = 0; i < parts.length - 1; i++) {
+                    path += parts[i] + '/';
+                    dirs.add(path);
+                }
+            }
+            const all = [...dirs, ...files];
+            return all.sort();
         }
     }
     catch (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.5",
+  "version": "1.1.7",
   "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,7 +16,7 @@
     "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",