roxify 1.1.4 → 1.1.5

package/README.md

@@ -15,6 +15,8 @@ Key benefits:
 - **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.
+- **Archive Support**: Pack directories into archives, list contents without decoding, and extract individual files selectively.
+- **Central Directory**: Access file lists without passphrase, even for encrypted archives.
 
 ## Installation
 
@@ -37,8 +39,9 @@ If no output name is provided:
 
 **Commands:**
 
-- `encode <input> [output]` — Encode file to PNG
-- `decode <input> [output]` — Decode PNG to file
+- `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:**
 
@@ -46,6 +49,7 @@ If no output name is provided:
 - `-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.
@@ -53,46 +57,109 @@ Run `npx rox help` for full options.
 ## API Usage
 
 ```js
-import { encodeBinaryToPng, decodePngToBinary } from 'roxify';
+import { encodeBinaryToPng, decodePngToBinary, listFilesInPng } from 'roxify';
 
+// Encode a file
 const data = Buffer.from('Hello world');
 const png = await encodeBinaryToPng(data, {
   mode: 'screenshot',
   name: 'message.txt',
 });
 
+// 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);
+
+// Selective extraction
+const result = await decodePngToBinary(png, { files: ['file1.txt'] });
+if (result.files) {
+  // result.files contains only the selected files
+}
+```
+
+## Example: Progress Logging
+
+```js
+import { encodeBinaryToPng, decodePngToBinary } from 'roxify';
+
+const data = Buffer.from('Large data to encode...');
+
+// 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)`);
+    }
+  },
+});
+
+// Decode with progress logging
+const { buf } = await decodePngToBinary(png, {
+  onProgress: (info) => {
+    console.log(`Decoding phase: ${info.phase}`);
+  },
+});
 ```
 
 **API:**
 
 - `encodeBinaryToPng(input: Buffer, opts?: EncodeOptions): Promise<Buffer>`
-- `decodePngToBinary(pngBuf: Buffer): Promise<{ buf: Buffer, meta?: { name?: string } }>`
+- `decodePngToBinary(pngBuf: Buffer, opts?: DecodeOptions): Promise<DecodeResult>`
+- `listFilesInPng(pngBuf: Buffer): string[] | null`
 
-**Options:**
+**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:**
 
-## Example: Express Endpoint
+- `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 express from 'express';
-import { encodeBinaryToPng } from 'roxify';
-
-const app = express();
-app.get('/payload.png', async (req, res) => {
-  const payload = Buffer.from('Embedded data');
-  const png = await encodeBinaryToPng(payload, { mode: 'screenshot' });
-  res.setHeader('Content-Type', 'image/png');
-  res.send(png);
+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,
 });
-app.listen(3000);
+
+// 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

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
-import { readFileSync, writeFileSync } from 'fs';
-import { basename, dirname, resolve } from 'path';
-import { DataFormatError, decodePngToBinary, encodeBinaryToPng, IncorrectPassphraseError, PassphraseRequiredError, } from './index.js';
-const VERSION = '1.1.4';
+import cliProgress from 'cli-progress';
+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';
 function showHelp() {
     console.log(`
 ROX CLI — Encode/decode binary in PNG
@@ -11,8 +13,9 @@ Usage:
   npx rox <command> [options]
 
 Commands:
-  encode <input> [output]   Encode file to PNG
-  decode <input> [output]   Decode PNG to original file
+  encode <input>... [output]   Encode one or more files/directories into a PNG
+  decode <input> [output]   Decode PNG to original file
+  list <input>               List files in a Rox PNG archive
 
 Options:
   -p, --passphrase <pass>   Use passphrase (AES-256-GCM)
@@ -21,6 +24,7 @@ Options:
   -e, --encrypt <type>      auto|aes|xor|none
   --no-compress             Disable compression
   -o, --output <path>       Output file path
+  --files <list>            Extract only specified files (comma-separated)
   --view-reconst            Export the reconstituted PNG for debugging
   --debug                   Export debug images (doubled.png, reconstructed.png)
   -v, --verbose             Show detailed errors
@@ -55,6 +59,10 @@ function parseArgs(args) {
                 parsed.debugDir = args[i + 1];
                 i += 2;
             }
+            else if (key === 'files') {
+                parsed.files = args[i + 1].split(',');
+                i += 2;
+            }
             else {
                 const value = args[i + 1];
                 parsed[key] = value;
@@ -107,25 +115,92 @@ function parseArgs(args) {
 }
 async function encodeCommand(args) {
     const parsed = parseArgs(args);
-    const [inputPath, outputPath] = parsed._;
-    if (!inputPath) {
+    const inputPaths = parsed.output
+        ? parsed._
+        : parsed._.length > 1
+            ? parsed._.slice(0, -1)
+            : parsed._;
+    const outputPath = parsed.output
+        ? undefined
+        : parsed._.length > 1
+            ? parsed._[parsed._.length - 1]
+            : undefined;
+    const firstInput = inputPaths[0];
+    if (!firstInput) {
         console.error('Error: Input file required');
         console.log('Usage: npx rox encode <input> [output] [options]');
         process.exit(1);
     }
-    const resolvedInput = resolve(inputPath);
-    const resolvedOutput = parsed.output || outputPath || inputPath.replace(/(\.[^.]+)?$/, '.png');
+    const resolvedInputs = inputPaths.map((p) => resolve(p));
+    const resolvedOutput = parsed.output ||
+        outputPath ||
+        (inputPaths.length === 1
+            ? firstInput.replace(/(\.[^.]+)?$/, '.png')
+            : 'archive.png');
+    let options = {};
     try {
-        console.log(`Reading: ${resolvedInput}`);
-        const startRead = Date.now();
-        const inputBuffer = readFileSync(resolvedInput);
-        const readTime = Date.now() - startRead;
-        console.log(`Read ${(inputBuffer.length / 1024 / 1024).toFixed(2)} MB in ${readTime}ms`);
-        const options = {
+        let inputBuffer;
+        let displayName;
+        if (inputPaths.length > 1) {
+            console.log(`Packing ${inputPaths.length} inputs...`);
+            const bar = new cliProgress.SingleBar({
+                format: ' {bar} {percentage}% | {step} | {mbValue}/{mbTotal} MB',
+            }, cliProgress.Presets.shades_classic);
+            let totalBytes = 0;
+            const onProgress = (readBytes, total) => {
+                if (totalBytes === 0) {
+                    totalBytes = total;
+                    bar.start(totalBytes, 0, {
+                        step: 'Reading files',
+                        mbValue: '0.00',
+                        mbTotal: (totalBytes / 1024 / 1024).toFixed(2),
+                    });
+                }
+                bar.update(readBytes, {
+                    step: 'Reading files',
+                    mbValue: (readBytes / 1024 / 1024).toFixed(2),
+                });
+            };
+            const packResult = packPaths(inputPaths, undefined, onProgress);
+            bar.stop();
+            inputBuffer = packResult.buf;
+            console.log(`Packed ${packResult.list.length} files -> ${(inputBuffer.length /
+                1024 /
+                1024).toFixed(2)} MB`);
+            displayName = parsed.outputName || 'archive';
+            options.includeFileList = true;
+            options.fileList = packResult.list;
+        }
+        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]);
+                inputBuffer = packResult.buf;
+                console.log(`Packed ${packResult.list.length} files -> ${(inputBuffer.length /
+                    1024 /
+                    1024).toFixed(2)} MB`);
+                displayName = parsed.outputName || basename(resolvedInput);
+                options.includeFileList = true;
+                options.fileList = packResult.list;
+            }
+            else {
+                const startRead = Date.now();
+                inputBuffer = readFileSync(resolvedInput);
+                const readTime = Date.now() - startRead;
+                console.log('');
+                displayName = basename(resolvedInput);
+            }
+        }
+        Object.assign(options, {
             mode: parsed.mode || 'screenshot',
-            name: basename(resolvedInput),
+            name: displayName,
             brQuality: parsed.quality !== undefined ? parsed.quality : 11,
-        };
+        });
         if (parsed.noCompress) {
             options.compression = 'none';
         }
@@ -133,10 +208,45 @@ async function encodeCommand(args) {
             options.passphrase = parsed.passphrase;
             options.encrypt = parsed.encrypt || 'aes';
         }
-        console.log(`Encoding ${basename(resolvedInput)} -> ${resolvedOutput}`);
+        console.log(`Encoding ${displayName} -> ${resolvedOutput}\n`);
+        const encodeBar = new cliProgress.SingleBar({
+            format: ' {bar} {percentage}% | {step} | {elapsed}s',
+        }, cliProgress.Presets.shades_classic);
+        let totalMB = Math.max(1, Math.round(inputBuffer.length / 1024 / 1024));
+        encodeBar.start(100, 0, {
+            step: 'Starting',
+            elapsed: '0',
+        });
         const startEncode = Date.now();
+        options.onProgress = (info) => {
+            let pct = 0;
+            if (info.phase === 'compress_progress') {
+                pct = (info.loaded / info.total) * 50;
+            }
+            else if (info.phase === 'compress_done') {
+                pct = 50;
+            }
+            else if (info.phase === 'encrypt_done') {
+                pct = 80;
+            }
+            else if (info.phase === 'png_gen') {
+                pct = 90;
+            }
+            else if (info.phase === 'done') {
+                pct = 100;
+            }
+            encodeBar.update(Math.floor(pct), {
+                step: info.phase.replace('_', ' '),
+                elapsed: String(Math.floor((Date.now() - startEncode) / 1000)),
+            });
+        };
         const output = await encodeBinaryToPng(inputBuffer, options);
         const encodeTime = Date.now() - startEncode;
+        encodeBar.update(100, {
+            step: 'done',
+            elapsed: String(Math.floor(encodeTime / 1000)),
+        });
+        encodeBar.stop();
         writeFileSync(resolvedOutput, output);
         const outputSize = (output.length / 1024 / 1024).toFixed(2);
         const inputSize = (inputBuffer.length / 1024 / 1024).toFixed(2);
@@ -146,6 +256,7 @@ async function encodeCommand(args) {
         console.log(`  Output: ${outputSize} MB (${ratio}% of original)`);
         console.log(`  Time:   ${encodeTime}ms`);
         console.log(`  Saved:  ${resolvedOutput}`);
+        console.log(' ');
     }
     catch (err) {
         console.error('Error: Failed to encode file. Use --verbose for details.');
@@ -165,6 +276,7 @@ async function decodeCommand(args) {
     const resolvedInput = resolve(inputPath);
     try {
         const inputBuffer = readFileSync(resolvedInput);
+        console.log(' ');
         console.log(`Reading: ${resolvedInput}`);
         const options = {};
         if (parsed.passphrase) {
@@ -173,20 +285,74 @@ async function decodeCommand(args) {
         if (parsed.debug) {
             options.debugDir = dirname(resolvedInput);
         }
+        if (parsed.files) {
+            options.files = parsed.files;
+        }
+        console.log(' ');
+        console.log(' ');
         console.log(`Decoding...`);
+        console.log(' ');
+        const decodeBar = new cliProgress.SingleBar({
+            format: ' {bar} {percentage}% | {step} | {elapsed}s',
+        }, cliProgress.Presets.shades_classic);
+        decodeBar.start(100, 0, {
+            step: 'Decoding',
+            elapsed: '0',
+        });
         const startDecode = Date.now();
+        options.onProgress = (info) => {
+            let pct = 50;
+            if (info.phase === 'done')
+                pct = 100;
+            decodeBar.update(pct, {
+                step: 'Decoding',
+                elapsed: String(Math.floor((Date.now() - startDecode) / 1000)),
+            });
+        };
         const result = await decodePngToBinary(inputBuffer, options);
         const decodeTime = Date.now() - startDecode;
-        const resolvedOutput = parsed.output || outputPath || result.meta?.name || 'decoded.bin';
-        writeFileSync(resolvedOutput, result.buf);
-        const outputSize = (result.buf.length / 1024 / 1024).toFixed(2);
-        console.log(`\nSuccess!`);
-        if (result.meta?.name) {
-            console.log(`  Original name: ${result.meta.name}`);
+        decodeBar.update(100, {
+            step: 'done',
+            elapsed: String(Math.floor(decodeTime / 1000)),
+        });
+        decodeBar.stop();
+        if (result.files) {
+            const baseDir = parsed.output || outputPath || 'extracted';
+            for (const file of result.files) {
+                const fullPath = join(baseDir, file.path);
+                const dir = dirname(fullPath);
+                mkdirSync(dir, { recursive: true });
+                writeFileSync(fullPath, file.buf);
+            }
+            console.log(`\nSuccess!`);
+            console.log(`Extracted ${result.files.length} files to ${baseDir}`);
+            console.log(`Time: ${decodeTime}ms`);
         }
-        console.log(`  Output size:   ${outputSize} MB`);
-        console.log(`  Time:          ${decodeTime}ms`);
-        console.log(`  Saved:         ${resolvedOutput}`);
+        else if (result.buf) {
+            const unpacked = unpackBuffer(result.buf);
+            if (unpacked) {
+                const baseDir = parsed.output || outputPath || result.meta?.name || 'unpacked';
+                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}`);
+            }
+            else {
+                const resolvedOutput = parsed.output || outputPath || result.meta?.name || 'decoded.bin';
+                writeFileSync(resolvedOutput, 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`);
+                console.log(`  Time:          ${decodeTime}ms`);
+                console.log(`  Saved:         ${resolvedOutput}`);
+            }
+        }
+        console.log(' ');
     }
     catch (err) {
         if (err instanceof PassphraseRequiredError ||
@@ -214,6 +380,35 @@ async function decodeCommand(args) {
         process.exit(1);
     }
 }
+async function listCommand(args) {
+    const parsed = parseArgs(args);
+    const [inputPath] = parsed._;
+    if (!inputPath) {
+        console.error('Error: Input PNG file required');
+        console.log('Usage: npx rox list <input>');
+        process.exit(1);
+    }
+    const resolvedInput = resolve(inputPath);
+    try {
+        const inputBuffer = readFileSync(resolvedInput);
+        const fileList = listFilesInPng(inputBuffer);
+        if (fileList) {
+            console.log(`Files in ${resolvedInput}:`);
+            for (const file of fileList) {
+                console.log(`  ${file}`);
+            }
+        }
+        else {
+            console.log('No file list found in the archive.');
+        }
+    }
+    catch (err) {
+        console.error('Failed to list files. Use --verbose for details.');
+        if (parsed.verbose)
+            console.error('Details:', err.stack || err.message);
+        process.exit(1);
+    }
+}
 async function main() {
     const args = process.argv.slice(2);
     if (args.length === 0 || args[0] === 'help' || args[0] === '--help') {
@@ -233,6 +428,9 @@ async function main() {
         case 'decode':
             await decodeCommand(commandArgs);
             break;
+        case 'list':
+            await listCommand(commandArgs);
+            break;
         default:
             console.error(`Unknown command: ${command}`);
             console.log('Run "npx rox help" for usage information');

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="node" />
 /// <reference types="node" />
+import { PackedFile } from './pack.js';
 export declare class PassphraseRequiredError extends Error {
     constructor(message?: string);
 }
@@ -63,6 +64,15 @@ export interface EncodeOptions {
      * @defaultValue `true`
      */
     includeName?: boolean;
+    /**
+     * Whether to include the file list in the encoded metadata for archives.
+     * @defaultValue `false`
+     */
+    includeFileList?: boolean;
+    /**
+     * List of file paths for archives (used if includeFileList is true).
+     */
+    fileList?: string[];
     /**
      * Brotli compression quality (0-11).
      * - Lower values = faster compression, larger output
@@ -70,6 +80,16 @@ export interface EncodeOptions {
      * @defaultValue `1` (optimized for speed)
      */
     brQuality?: number;
+    onProgress?: (info: {
+        phase: string;
+        loaded?: number;
+        total?: number;
+    }) => void;
+    /**
+     * Whether to display a progress bar in the console.
+     * @defaultValue `false`
+     */
+    showProgress?: boolean;
 }
 /**
  * Result of decoding a PNG back to binary data.
@@ -79,7 +99,7 @@ export interface DecodeResult {
     /**
      * The decoded binary data.
      */
-    buf: Buffer;
+    buf?: Buffer;
     /**
      * Metadata extracted from the encoded image.
      */
@@ -89,6 +109,10 @@ export interface DecodeResult {
          */
         name?: string;
     };
+    /**
+     * Extracted files, if selective extraction was requested.
+     */
+    files?: PackedFile[];
 }
 /**
  * Options for decoding a PNG back to binary data.
@@ -103,6 +127,23 @@ export interface DecodeOptions {
      * Directory to save debug images (doubled.png, reconstructed.png).
      */
     debugDir?: string;
+    /**
+     * List of files to extract selectively from archives.
+     */
+    files?: string[];
+    /**
+     * Progress callback for decoding phases.
+     */
+    onProgress?: (info: {
+        phase: string;
+        loaded?: number;
+        total?: number;
+    }) => void;
+    /**
+     * Whether to display a progress bar in the console.
+     * @defaultValue `false`
+     */
+    showProgress?: boolean;
 }
 export declare function cropAndReconstitute(input: Buffer, debugDir?: string): Promise<Buffer>;
 /**
@@ -123,3 +164,11 @@ export declare function encodeBinaryToPng(input: Buffer, opts?: EncodeOptions):
  * @public
  */
 export declare function decodePngToBinary(pngBuf: Buffer, opts?: DecodeOptions): Promise<DecodeResult>;
+export { packPaths, unpackBuffer } from './pack.js';
+/**
+ * List files in a Rox PNG archive without decoding the full payload.
+ * Returns the file list if available, otherwise null.
+ * @param pngBuf - PNG data
+ * @public
+ */
+export declare function listFilesInPng(pngBuf: Buffer): string[] | null;

package/dist/index.js

@@ -1,10 +1,12 @@
 import { compress as zstdCompress, decompress as zstdDecompress, } from '@mongodb-js/zstd';
+import cliProgress from 'cli-progress';
 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';
 import * as zlib from 'zlib';
+import { unpackBuffer } from './pack.js';
 const CHUNK_TYPE = 'rXDT';
 const MAGIC = Buffer.from('ROX1');
 const PIXEL_MAGIC = Buffer.from('PXL1');
@@ -394,11 +396,60 @@ export async function cropAndReconstitute(input, debugDir) {
  * @public
  */
 export async function encodeBinaryToPng(input, opts = {}) {
+    let progressBar = null;
+    if (opts.showProgress) {
+        progressBar = new cliProgress.SingleBar({
+            format: ' {bar} {percentage}% | {step} | {elapsed}s',
+        }, cliProgress.Presets.shades_classic);
+        progressBar.start(100, 0, { step: 'Starting', elapsed: '0' });
+        const startTime = Date.now();
+        if (!opts.onProgress) {
+            opts.onProgress = (info) => {
+                let pct = 0;
+                if (info.phase === 'compress_progress' && info.loaded && info.total) {
+                    pct = (info.loaded / info.total) * 50;
+                }
+                else if (info.phase === 'compress_done') {
+                    pct = 50;
+                }
+                else if (info.phase === 'encrypt_done') {
+                    pct = 80;
+                }
+                else if (info.phase === 'png_gen') {
+                    pct = 90;
+                }
+                else if (info.phase === 'done') {
+                    pct = 100;
+                }
+                progressBar.update(Math.floor(pct), {
+                    step: info.phase.replace('_', ' '),
+                    elapsed: String(Math.floor((Date.now() - startTime) / 1000)),
+                });
+            };
+        }
+    }
     let payload = Buffer.concat([MAGIC, input]);
     const brQuality = typeof opts.brQuality === 'number' ? opts.brQuality : 11;
     const mode = opts.mode === undefined ? 'screenshot' : opts.mode;
     const compression = opts.compression || 'zstd';
-    payload = Buffer.from(await zstdCompress(payload, 22));
+    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)
+            opts.onProgress({
+                phase: 'compress_progress',
+                loaded: i + chunk.length,
+                total: payload.length,
+            });
+    }
+    payload = Buffer.concat(compressedChunks);
+    if (opts.onProgress)
+        opts.onProgress({ phase: 'compress_done', loaded: payload.length });
     if (opts.passphrase && !opts.encrypt) {
         opts.encrypt = 'aes';
     }
@@ -418,6 +469,8 @@ export async function encodeBinaryToPng(input, opts = {}) {
     }
     if (opts.passphrase && opts.encrypt && opts.encrypt !== 'auto') {
         const encChoice = opts.encrypt;
+        if (opts.onProgress)
+            opts.onProgress({ phase: 'encrypt_start' });
         if (encChoice === 'aes') {
             const salt = randomBytes(16);
             const iv = randomBytes(12);
@@ -431,14 +484,20 @@ export async function encodeBinaryToPng(input, opts = {}) {
         else if (encChoice === 'xor') {
             const xored = applyXor(payload, opts.passphrase);
             payload = Buffer.concat([Buffer.from([ENC_XOR]), xored]);
+            if (opts.onProgress)
+                opts.onProgress({ phase: 'encrypt_done' });
         }
         else if (encChoice === 'none') {
             payload = Buffer.concat([Buffer.from([ENC_NONE]), payload]);
+            if (opts.onProgress)
+                opts.onProgress({ phase: 'encrypt_done' });
         }
     }
     else {
         payload = Buffer.concat([Buffer.from([ENC_NONE]), payload]);
     }
+    if (opts.onProgress)
+        opts.onProgress({ phase: 'meta_prep_done', loaded: payload.length });
     const metaParts = [];
     const includeName = opts.includeName === undefined ? true : !!opts.includeName;
     if (includeName && opts.name) {
@@ -532,9 +591,9 @@ export async function encodeBinaryToPng(input, opts = {}) {
                 }
             }
         }
-        return await sharp(raw, {
-            raw: { width, height, channels: 3 },
-        })
+        if (opts.onProgress)
+            opts.onProgress({ phase: 'png_gen' });
+        let bufScr = await sharp(raw, { raw: { width, height, channels: 3 } })
             .png({
             compressionLevel: 9,
             palette: false,
@@ -542,6 +601,19 @@ export async function encodeBinaryToPng(input, opts = {}) {
             adaptiveFiltering: true,
         })
             .toBuffer();
+        if (opts.includeFileList && opts.fileList) {
+            const chunks = extract(bufScr);
+            const fileListChunk = {
+                name: 'rXFL',
+                data: Buffer.from(JSON.stringify(opts.fileList), 'utf8'),
+            };
+            chunks.splice(-1, 0, fileListChunk);
+            bufScr = Buffer.from(encode(chunks));
+        }
+        if (opts.onProgress)
+            opts.onProgress({ phase: 'done', loaded: bufScr.length });
+        progressBar?.stop();
+        return bufScr;
     }
     if (mode === 'pixel') {
         const nameBuf = opts.name
@@ -600,10 +672,15 @@ export async function encodeBinaryToPng(input, opts = {}) {
         chunksPixel.push({ name: 'IHDR', data: ihdrData });
         chunksPixel.push({ name: 'IDAT', data: idatData });
         chunksPixel.push({ name: 'IEND', data: Buffer.alloc(0) });
+        if (opts.onProgress)
+            opts.onProgress({ phase: 'png_gen' });
         const tmp = Buffer.from(encode(chunksPixel));
         const outPng = tmp.slice(0, 8).toString('hex') === PNG_HEADER_HEX
             ? tmp
             : Buffer.concat([PNG_HEADER, tmp]);
+        if (opts.onProgress)
+            opts.onProgress({ phase: 'done', loaded: outPng.length });
+        progressBar?.stop();
         return outPng;
     }
     if (mode === 'compact') {
@@ -633,11 +710,23 @@ export async function encodeBinaryToPng(input, opts = {}) {
         chunks2.push({ name: 'IHDR', data: ihdrData });
         chunks2.push({ name: 'IDAT', data: idatData });
         chunks2.push({ name: CHUNK_TYPE, data: meta });
+        if (opts.includeFileList && opts.fileList) {
+            chunks2.push({
+                name: 'rXFL',
+                data: Buffer.from(JSON.stringify(opts.fileList), 'utf8'),
+            });
+        }
         chunks2.push({ name: 'IEND', data: Buffer.alloc(0) });
+        if (opts.onProgress)
+            opts.onProgress({ phase: 'png_gen' });
         const out = Buffer.from(encode(chunks2));
-        return out.slice(0, 8).toString('hex') === PNG_HEADER_HEX
+        const outBuf = out.slice(0, 8).toString('hex') === PNG_HEADER_HEX
             ? out
             : Buffer.concat([PNG_HEADER, out]);
+        if (opts.onProgress)
+            opts.onProgress({ phase: 'done', loaded: outBuf.length });
+        progressBar?.stop();
+        return outBuf;
     }
     throw new Error(`Unsupported mode: ${mode}`);
 }
@@ -650,6 +739,34 @@ export async function encodeBinaryToPng(input, opts = {}) {
  * @public
  */
 export async function decodePngToBinary(pngBuf, opts = {}) {
+    let progressBar = null;
+    if (opts.showProgress) {
+        progressBar = new cliProgress.SingleBar({
+            format: ' {bar} {percentage}% | {step} | {elapsed}s',
+        }, cliProgress.Presets.shades_classic);
+        progressBar.start(100, 0, { step: 'Starting', elapsed: '0' });
+        const startTime = Date.now();
+        if (!opts.onProgress) {
+            opts.onProgress = (info) => {
+                let pct = 0;
+                if (info.phase === 'start') {
+                    pct = 10;
+                }
+                else if (info.phase === 'decompress') {
+                    pct = 50;
+                }
+                else if (info.phase === 'done') {
+                    pct = 100;
+                }
+                progressBar.update(Math.floor(pct), {
+                    step: info.phase.replace('_', ' '),
+                    elapsed: String(Math.floor((Date.now() - startTime) / 1000)),
+                });
+            };
+        }
+    }
+    if (opts.onProgress)
+        opts.onProgress({ phase: 'start' });
     let processedBuf = pngBuf;
     try {
         const info = await sharp(pngBuf).metadata();
@@ -666,6 +783,8 @@ export async function decodePngToBinary(pngBuf, opts = {}) {
         }
     }
     catch (e) { }
+    if (opts.onProgress)
+        opts.onProgress({ phase: 'processed' });
     if (processedBuf.slice(0, MAGIC.length).equals(MAGIC)) {
         const d = processedBuf.slice(MAGIC.length);
         const nameLen = d[0];
@@ -677,6 +796,8 @@ export async function decodePngToBinary(pngBuf, opts = {}) {
         }
         const rawPayload = d.slice(idx);
         let payload = tryDecryptIfNeeded(rawPayload, opts.passphrase);
+        if (opts.onProgress)
+            opts.onProgress({ phase: 'decompress' });
         try {
             payload = await tryZstdDecompress(payload);
         }
@@ -690,6 +811,9 @@ export async function decodePngToBinary(pngBuf, opts = {}) {
             throw new Error('Invalid ROX format (ROX direct: missing ROX1 magic after decompression)');
         }
         payload = payload.slice(MAGIC.length);
+        if (opts.onProgress)
+            opts.onProgress({ phase: 'done' });
+        progressBar?.stop();
         return { buf: payload, meta: { name } };
     }
     let chunks = [];
@@ -731,6 +855,8 @@ 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.onProgress)
+            opts.onProgress({ phase: 'decompress' });
         try {
             payload = await tryZstdDecompress(payload);
         }
@@ -744,6 +870,18 @@ export async function decodePngToBinary(pngBuf, opts = {}) {
             throw new DataFormatError('Invalid ROX format (compact mode: missing ROX1 magic after decompression)');
         }
         payload = payload.slice(MAGIC.length);
+        if (opts.files) {
+            const unpacked = unpackBuffer(payload, opts.files);
+            if (unpacked) {
+                if (opts.onProgress)
+                    opts.onProgress({ phase: 'done' });
+                progressBar?.stop();
+                return { files: unpacked.files, meta: { name } };
+            }
+        }
+        if (opts.onProgress)
+            opts.onProgress({ phase: 'done' });
+        progressBar?.stop();
         return { buf: payload, meta: { name } };
     }
     try {
@@ -1087,6 +1225,18 @@ export async function decodePngToBinary(pngBuf, opts = {}) {
                     throw new DataFormatError('Invalid ROX format (pixel mode: missing ROX1 magic after decompression)');
                 }
                 payload = payload.slice(MAGIC.length);
+                if (opts.files) {
+                    const unpacked = unpackBuffer(payload, opts.files);
+                    if (unpacked) {
+                        if (opts.onProgress)
+                            opts.onProgress({ phase: 'done' });
+                        progressBar?.stop();
+                        return { files: unpacked.files, meta: { name } };
+                    }
+                }
+                if (opts.onProgress)
+                    opts.onProgress({ phase: 'done' });
+                progressBar?.stop();
                 return { buf: payload, meta: { name } };
             }
         }
@@ -1111,3 +1261,24 @@ export async function decodePngToBinary(pngBuf, opts = {}) {
     }
     throw new DataFormatError('No valid data found in image');
 }
+export { packPaths, unpackBuffer } from './pack.js';
+/**
+ * List files in a Rox PNG archive without decoding the full payload.
+ * Returns the file list if available, otherwise null.
+ * @param pngBuf - PNG data
+ * @public
+ */
+export function listFilesInPng(pngBuf) {
+    try {
+        const chunks = extract(pngBuf);
+        const fileListChunk = chunks.find((c) => c.name === 'rXFL');
+        if (fileListChunk) {
+            const data = Buffer.isBuffer(fileListChunk.data)
+                ? fileListChunk.data
+                : Buffer.from(fileListChunk.data);
+            return JSON.parse(data.toString('utf8'));
+        }
+    }
+    catch (e) { }
+    return null;
+}

package/dist/pack.d.ts

@@ -0,0 +1,16 @@
+/// <reference types="node" />
+/// <reference types="node" />
+export interface PackedFile {
+    path: string;
+    buf: Buffer;
+}
+export declare function packPaths(paths: string[], baseDir?: string, onProgress?: (readBytes: number, totalBytes: number) => void): {
+    buf: Buffer;
+    list: string[];
+};
+export declare function unpackBuffer(buf: Buffer, fileList?: string[]): {
+    files: {
+        path: string;
+        buf: Buffer;
+    }[];
+} | null;

package/dist/pack.js

@@ -0,0 +1,85 @@
+import { readFileSync, readdirSync, statSync } from 'fs';
+import { join, relative, resolve, sep } from 'path';
+function collectFiles(paths) {
+    const files = [];
+    for (const p of paths) {
+        const abs = resolve(p);
+        const st = statSync(abs);
+        if (st.isFile()) {
+            files.push(abs);
+        }
+        else if (st.isDirectory()) {
+            const names = readdirSync(abs);
+            const childPaths = names.map((n) => join(abs, n));
+            files.push(...collectFiles(childPaths));
+        }
+    }
+    return files;
+}
+export function packPaths(paths, baseDir, onProgress) {
+    const files = collectFiles(paths);
+    const base = baseDir ? resolve(baseDir) : process.cwd();
+    const parts = [];
+    const list = [];
+    let total = 0;
+    const sizes = files.map((f) => {
+        const st = statSync(f);
+        total += st.size;
+        return st.size;
+    });
+    let readSoFar = 0;
+    for (let idx = 0; idx < files.length; idx++) {
+        const f = files[idx];
+        const rel = relative(base, f).split(sep).join('/');
+        const content = readFileSync(f);
+        const nameBuf = Buffer.from(rel, 'utf8');
+        const nameLen = Buffer.alloc(2);
+        nameLen.writeUInt16BE(nameBuf.length, 0);
+        const sizeBuf = Buffer.alloc(8);
+        sizeBuf.writeBigUInt64BE(BigInt(content.length), 0);
+        parts.push(nameLen, nameBuf, sizeBuf, content);
+        list.push(rel);
+        readSoFar += sizes[idx];
+        if (onProgress)
+            onProgress(readSoFar, total);
+    }
+    const header = Buffer.alloc(8);
+    header.writeUInt32BE(0x524f5850, 0);
+    header.writeUInt32BE(files.length, 4);
+    parts.unshift(header);
+    return { buf: Buffer.concat(parts), list };
+}
+export function unpackBuffer(buf, fileList) {
+    if (buf.length < 8)
+        return null;
+    const header = buf.slice(0, 8);
+    if (header.readUInt32BE(0) !== 0x524f5850)
+        return null;
+    const fileCount = header.readUInt32BE(4);
+    let offset = 8;
+    const files = [];
+    for (let i = 0; i < fileCount; i++) {
+        if (offset + 2 > buf.length)
+            return null;
+        const nameLen = buf.readUInt16BE(offset);
+        offset += 2;
+        if (offset + nameLen > buf.length)
+            return null;
+        const name = buf.slice(offset, offset + nameLen).toString('utf8');
+        offset += nameLen;
+        if (offset + 8 > buf.length)
+            return null;
+        const size = buf.readBigUInt64BE(offset);
+        offset += 8;
+        if (offset + Number(size) > buf.length)
+            return null;
+        const content = buf.slice(offset, offset + Number(size));
+        offset += Number(size);
+        files.push({ path: name, buf: content });
+    }
+    if (fileList) {
+        const filtered = files.filter((f) => fileList.includes(f.path));
+        return { files: filtered };
+    }
+    return { files };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roxify",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "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",
@@ -15,7 +15,8 @@
   "scripts": {
     "build": "tsc",
     "check-publish": "node ../scripts/check-publish.js roxify",
-    "cli": "node dist/cli.js"
+    "cli": "node dist/cli.js",
+    "test": "node test/pack.test.js"
   },
   "keywords": [
     "steganography",
@@ -40,12 +41,14 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@mongodb-js/zstd": "^7.0.0",
+    "@mongodb-js/zstd": "^2.0.1",
     "png-chunks-encode": "^1.0.0",
     "png-chunks-extract": "^1.0.0",
-    "sharp": "^0.34.5"
+    "sharp": "^0.34.5",
+    "cli-progress": "^3.9.1"
   },
   "devDependencies": {
-    "typescript": "^4.9.5"
+    "typescript": "^4.9.5",
+    "@types/cli-progress": "^3.9.0"
   }
 }