roxify 1.1.12 → 1.2.1

package/README.md

@@ -103,3 +103,15 @@ const pngBuffer = await encodeBinaryToPng(inputBuffer, {
 ## License
 
 This package is proprietary (UNLICENSED). The repository remains private; the package is published to npm for distribution. If there is significant community interest, it may be open-sourced in the future.
+
+## Minimal PNG container (minpng) 🔧
+
+This library includes a compact encoder/decoder that targets the smallest possible PNG container while guaranteeing pixel-perfect recovery from screenshots when no lossy filtering is applied.
+
+- Inputs must be raw RGB 8-bit buffers (no alpha).
+- Transformations used: Paeth 2D predictor (left/top), RGB decorrelation (G, R−G, B−G), zigzag traversal.
+- Compression: Zstd at maximum compression level.
+- Output: neutral PNG (no ICC/gamma/alpha), all data mapped to RGB bytes only.
+- The decoder searches for start/end markers and a compact header embedded in pixels to perform a reliable, deterministic roundtrip.
+
+Use `encodeMinPng(rgbBuf, width, height)` and `decodeMinPng(pngBuf)` from the public API (`roxify`).

package/dist/cli.js

@@ -145,29 +145,55 @@ async function encodeCommand(args) {
     try {
         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 encodeBar = new cliProgress.SingleBar({
+            format: ' {bar} {percentage}% | {step} | {elapsed}s',
+        }, cliProgress.Presets.shades_classic);
+        let barStarted = false;
+        const startEncode = Date.now();
+        let currentEncodeStep = 'Starting';
+        let displayedPct = 0;
+        let targetPct = 0;
+        const TICK_MS = 100;
+        const PCT_STEP = 1;
+        const encodeHeartbeat = setInterval(() => {
+            const elapsed = Date.now() - startEncode;
+            if (!barStarted) {
+                encodeBar.start(100, Math.floor(displayedPct), {
+                    step: currentEncodeStep,
+                    elapsed: '0',
                 });
-            };
+                barStarted = true;
+            }
+            if (displayedPct < targetPct) {
+                displayedPct = Math.min(displayedPct + PCT_STEP, targetPct);
+            }
+            else if (displayedPct < 99) {
+                displayedPct = Math.min(displayedPct + PCT_STEP, 99);
+            }
+            encodeBar.update(Math.floor(displayedPct), {
+                step: currentEncodeStep,
+                elapsed: String(Math.floor(elapsed / 1000)),
+            });
+        }, TICK_MS);
+        let totalBytes = 0;
+        let lastShownFile;
+        const onProgress = (readBytes, total, currentFile) => {
+            if (totalBytes === 0)
+                totalBytes = total;
+            const packPct = Math.floor((readBytes / totalBytes) * 25);
+            targetPct = Math.max(targetPct, packPct);
+            if (currentFile && currentFile !== lastShownFile) {
+                lastShownFile = currentFile;
+            }
+            currentEncodeStep = currentFile
+                ? `Reading files: ${currentFile}`
+                : 'Reading files';
+        };
+        if (inputPaths.length > 1) {
+            currentEncodeStep = 'Reading files';
             const packResult = packPaths(inputPaths, undefined, onProgress);
-            bar.stop();
             inputBuffer = packResult.buf;
+            console.log('');
             console.log(`Packed ${packResult.list.length} files -> ${(inputBuffer.length /
                 1024 /
                 1024).toFixed(2)} MB`);
@@ -180,8 +206,10 @@ async function encodeCommand(args) {
             const st = statSync(resolvedInput);
             if (st.isDirectory()) {
                 console.log(`Packing directory...`);
-                const packResult = packPaths([resolvedInput], resolvedInput);
+                currentEncodeStep = 'Reading files';
+                const packResult = packPaths([resolvedInput], resolvedInput, onProgress);
                 inputBuffer = packResult.buf;
+                console.log('');
                 console.log(`Packed ${packResult.list.length} files -> ${(inputBuffer.length /
                     1024 /
                     1024).toFixed(2)} MB`);
@@ -208,72 +236,68 @@ async function encodeCommand(args) {
             options.encrypt = parsed.encrypt || 'aes';
         }
         console.log(`Encoding ${displayName} -> ${resolvedOutput}\n`);
-        const encodeBar = new cliProgress.SingleBar({
-            format: ' {bar} {percentage}% | {step} | {elapsed}s',
-        }, cliProgress.Presets.shades_classic);
-        encodeBar.start(100, 0, {
-            step: 'Starting',
-            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;
             let stepLabel = 'Processing';
+            let pct = 0;
             if (info.phase === 'compress_start') {
-                pct = 5;
+                pct = 25;
                 stepLabel = 'Compressing';
             }
             else if (info.phase === 'compress_progress') {
-                pct = 5 + Math.floor((info.loaded / info.total) * 45);
+                pct = 25 + Math.floor((info.loaded / info.total) * 50);
                 stepLabel = 'Compressing';
             }
             else if (info.phase === 'compress_done') {
-                pct = 50;
+                pct = 75;
                 stepLabel = 'Compressed';
             }
             else if (info.phase === 'encrypt_start') {
-                pct = 60;
+                pct = 76;
                 stepLabel = 'Encrypting';
             }
             else if (info.phase === 'encrypt_done') {
-                pct = 75;
+                pct = 80;
                 stepLabel = 'Encrypted';
             }
             else if (info.phase === 'meta_prep_done') {
-                pct = 80;
+                pct = 82;
                 stepLabel = 'Preparing';
             }
             else if (info.phase === 'png_gen') {
-                pct = 90;
+                if (info.loaded !== undefined && info.total !== undefined) {
+                    pct = 82 + Math.floor((info.loaded / info.total) * 16);
+                }
+                else {
+                    pct = 98;
+                }
                 stepLabel = 'Generating PNG';
             }
+            else if (info.phase === 'optimizing') {
+                if (info.loaded !== undefined && info.total !== undefined) {
+                    pct = 82 + Math.floor((info.loaded / info.total) * 18);
+                }
+                else {
+                    pct = 98;
+                }
+                stepLabel = 'Optimizing PNG';
+            }
             else if (info.phase === 'done') {
                 pct = 100;
                 stepLabel = 'Done';
             }
-            currentEncodePct = pct;
+            targetPct = Math.max(targetPct, pct);
             currentEncodeStep = stepLabel;
-            encodeBar.update(Math.floor(pct), {
-                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)),
-        });
-        encodeBar.stop();
+        if (barStarted) {
+            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);
@@ -321,52 +345,61 @@ async function decodeCommand(args) {
         const decodeBar = new cliProgress.SingleBar({
             format: ' {bar} {percentage}% | {step} | {elapsed}s',
         }, cliProgress.Presets.shades_classic);
-        decodeBar.start(100, 0, {
-            step: 'Decoding',
-            elapsed: '0',
-        });
+        let barStarted = false;
         const startDecode = Date.now();
-        let currentPct = 50;
+        let currentPct = 0;
+        let targetPct = 0;
         let currentStep = 'Decoding';
         const heartbeat = setInterval(() => {
-            decodeBar.update(Math.floor(currentPct), {
-                step: currentStep,
-                elapsed: String(Math.floor((Date.now() - startDecode) / 1000)),
-            });
-        }, 1000);
+            if (currentPct < targetPct) {
+                currentPct = Math.min(currentPct + 2, targetPct);
+            }
+            if (!barStarted && targetPct > 0) {
+                decodeBar.start(100, Math.floor(currentPct), {
+                    step: currentStep,
+                    elapsed: String(Math.floor((Date.now() - startDecode) / 1000)),
+                });
+                barStarted = true;
+            }
+            else if (barStarted) {
+                decodeBar.update(Math.floor(currentPct), {
+                    step: currentStep,
+                    elapsed: String(Math.floor((Date.now() - startDecode) / 1000)),
+                });
+            }
+        }, 100);
         options.onProgress = (info) => {
             if (info.phase === 'decompress_start') {
-                currentPct = 50;
+                targetPct = 50;
                 currentStep = 'Decompressing';
             }
             else if (info.phase === 'decompress_progress' &&
                 info.loaded &&
                 info.total) {
-                currentPct = 50 + Math.floor((info.loaded / info.total) * 40);
+                targetPct = 50 + Math.floor((info.loaded / info.total) * 40);
                 currentStep = `Decompressing (${info.loaded}/${info.total})`;
             }
             else if (info.phase === 'decompress_done') {
-                currentPct = 90;
+                targetPct = 90;
                 currentStep = 'Decompressed';
             }
             else if (info.phase === 'done') {
-                currentPct = 100;
+                targetPct = 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 (barStarted) {
+            currentPct = 100;
+            decodeBar.update(100, {
+                step: 'done',
+                elapsed: String(Math.floor(decodeTime / 1000)),
+            });
+            decodeBar.stop();
+        }
         if (result.files) {
             const baseDir = parsed.output || outputPath || '.';
             for (const file of result.files) {

package/dist/index.d.ts

@@ -15,80 +15,22 @@ export declare class DataFormatError extends Error {
  * @public
  */
 export interface EncodeOptions {
-    /**
-     * Compression algorithm to use.
-     * - `'zstd'`: Zstandard compression (maximum compression for smallest files)
-     * @defaultValue `'zstd'`
-     */
     compression?: 'zstd';
-    /**
-     * Passphrase for encryption. If provided without `encrypt` option, defaults to AES-256-GCM.
-     */
     passphrase?: string;
-    /**
-     * Original filename to embed in the encoded data.
-     */
     name?: string;
-    /**
-     * Encoding mode to use:
-     * - `'compact'`: Minimal 1x1 PNG with data in custom chunk (smallest, fastest)
-     * - `'pixel'`: Encode data as RGB pixel values
-     * - `'screenshot'`: Optimized for screenshot-like appearance (recommended)
-     * @defaultValue `'screenshot'`
-     */
     mode?: 'compact' | 'pixel' | 'screenshot';
-    /**
-     * Encryption method:
-     * - `'auto'`: Try all methods and pick smallest result
-     * - `'aes'`: AES-256-GCM authenticated encryption (secure)
-     * - `'xor'`: Simple XOR cipher (legacy, not recommended)
-     * - `'none'`: No encryption
-     * @defaultValue `'aes'` when passphrase is provided
-     */
     encrypt?: 'auto' | 'aes' | 'xor' | 'none';
-    /**
-     * Internal flag to skip auto-detection. Not for public use.
-     * @internal
-     */
     _skipAuto?: boolean;
-    /**
-     * Output format:
-     * - `'auto'`: Choose best format automatically
-     * - `'png'`: Force PNG output
-     * - `'rox'`: Force raw ROX binary format (no PNG wrapper)
-     * @defaultValue `'auto'`
-     */
     output?: 'auto' | 'png' | 'rox';
-    /**
-     * Whether to include the filename in the encoded metadata.
-     * @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
-     * - Higher values = slower compression, smaller output
-     * @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;
 }
 /**
@@ -96,27 +38,15 @@ export interface EncodeOptions {
  * @public
  */
 export interface DecodeResult {
-    /**
-     * The decoded binary data.
-     */
     buf?: Buffer;
-    /**
-     * Metadata extracted from the encoded image.
-     */
     meta?: {
-        /**
-         * Original filename, if it was embedded during encoding.
-         */
         name?: string;
     };
-    /**
-     * Extracted files, if selective extraction was requested.
-     */
     files?: PackedFile[];
 }
+export declare function optimizePngBuffer(pngBuf: Buffer, fast?: boolean): Promise<Buffer>;
 /**
- * Options for decoding a PNG back to binary data.
- * @public
+ * Path to write decoded output directly to disk (streamed) to avoid high memory usage.
  */
 export interface DecodeOptions {
     /**
@@ -188,6 +118,7 @@ export declare function encodeBinaryToPng(input: Buffer, opts?: EncodeOptions):
  * writeFileSync(meta?.name ?? 'decoded.txt', buf);
  */
 export declare function decodePngToBinary(pngBuf: Buffer, opts?: DecodeOptions): Promise<DecodeResult>;
+export { decodeMinPng, encodeMinPng } from './minpng.js';
 export { packPaths, unpackBuffer } from './pack.js';
 /**
  * List files in a Rox PNG archive without decoding the full payload.