roxify 1.5.2 → 1.5.4

package/dist/minpng.d.ts

@@ -1,4 +1,18 @@
+/**
+ * Encode a buffer of raw RGB data into a minimal PNG (MinPNG format).
+ *
+ * @param rgb - Buffer of RGB data.
+ * @param width - Image width.
+ * @param height - Image height.
+ * @returns Promise resolving to a PNG Buffer.
+ */
 export declare function encodeMinPng(rgb: Buffer, width: number, height: number): Promise<Buffer>;
+/**
+ * Decode a minimal PNG (MinPNG) buffer into raw RGB data and dimensions.
+ *
+ * @param pngBuf - Buffer containing a MinPNG image.
+ * @returns Promise resolving to an object with buf, width, and height, or null if invalid.
+ */
 export declare function decodeMinPng(pngBuf: Buffer): Promise<{
     buf: Buffer;
     width: number;

package/dist/minpng.js

@@ -51,6 +51,14 @@ function zigzagOrderIndices(width, height) {
     }
     return indices;
 }
+/**
+ * Encode a buffer of raw RGB data into a minimal PNG (MinPNG format).
+ *
+ * @param rgb - Buffer of RGB data.
+ * @param width - Image width.
+ * @param height - Image height.
+ * @returns Promise resolving to a PNG Buffer.
+ */
 export async function encodeMinPng(rgb, width, height) {
     const w = width, h = height;
     const idx = (x, y) => (y * w + x) * 3;
@@ -177,6 +185,12 @@ export async function encodeMinPng(rgb, width, height) {
     }
     return Buffer.concat(output);
 }
+/**
+ * Decode a minimal PNG (MinPNG) buffer into raw RGB data and dimensions.
+ *
+ * @param pngBuf - Buffer containing a MinPNG image.
+ * @returns Promise resolving to an object with buf, width, and height, or null if invalid.
+ */
 export async function decodeMinPng(pngBuf) {
     const rawData = native.sharpToRaw(pngBuf);
     const data = rawData.pixels;

package/dist/utils/decoder.d.ts

@@ -1,2 +1,17 @@
 import { DecodeOptions, DecodeResult } from './types.js';
+/**
+ * Decode a ROX PNG or buffer into the original binary payload or files list.
+ *
+ * @param input - Buffer or path to a PNG file.
+ * @param opts - Optional decode options.
+ * @returns A Promise resolving to DecodeResult ({ buf, meta } or { files }).
+ *
+ * @example
+ * ```js
+ * import { decodePngToBinary } from 'roxify';
+ * const png = fs.readFileSync('out.png');
+ * const res = await decodePngToBinary(png);
+ * console.log(res.meta?.name, res.buf.toString('utf8'));
+ * ```
+ */
 export declare function decodePngToBinary(input: Buffer | string, opts?: DecodeOptions): Promise<DecodeResult>;

package/dist/utils/decoder.js

@@ -58,6 +58,21 @@ function convertToPng(buf, format) {
         catch (e) { }
     }
 }
+/**
+ * Decode a ROX PNG or buffer into the original binary payload or files list.
+ *
+ * @param input - Buffer or path to a PNG file.
+ * @param opts - Optional decode options.
+ * @returns A Promise resolving to DecodeResult ({ buf, meta } or { files }).
+ *
+ * @example
+ * ```js
+ * import { decodePngToBinary } from 'roxify';
+ * const png = fs.readFileSync('out.png');
+ * const res = await decodePngToBinary(png);
+ * console.log(res.meta?.name, res.buf.toString('utf8'));
+ * ```
+ */
 export async function decodePngToBinary(input, opts = {}) {
     let pngBuf;
     if (Buffer.isBuffer(input)) {
@@ -347,8 +362,17 @@ export async function decodePngToBinary(input, opts = {}) {
             logicalData = rawRGB;
         }
         else {
+            if (process.env.ROX_DEBUG || opts.debugDir) {
+                console.log('DEBUG: about to call cropAndReconstitute, debugDir=', opts.debugDir);
+            }
             const reconstructed = await cropAndReconstitute(processedBuf, opts.debugDir);
+            if (process.env.ROX_DEBUG || opts.debugDir) {
+                console.log('DEBUG: cropAndReconstitute returned, reconstructed len=', reconstructed.length);
+            }
             const rawData = native.sharpToRaw(reconstructed);
+            if (process.env.ROX_DEBUG || opts.debugDir) {
+                console.log('DEBUG: rawData from reconstructed:', rawData.width, 'x', rawData.height, 'pixels=', Math.floor(rawData.pixels.length / 3));
+            }
             logicalWidth = rawData.width;
             logicalHeight = rawData.height;
             logicalData = Buffer.from(rawData.pixels);
@@ -596,6 +620,16 @@ export async function decodePngToBinary(input, opts = {}) {
                 const markerEndBytes = colorsToBytes(MARKER_END);
                 console.log('DEBUG: MARKER_END index:', pixelBytes.indexOf(markerEndBytes));
             }
+            if (opts.debugDir) {
+                try {
+                    console.log('DEBUG: writing extracted pixel bytes to', opts.debugDir);
+                    writeFileSync(join(opts.debugDir, 'extracted-pixel-bytes.bin'), pixelBytes);
+                    writeFileSync(join(opts.debugDir, 'extracted-pixel-head.hex'), pixelBytes.slice(0, 512).toString('hex'));
+                }
+                catch (e) {
+                    console.log('DEBUG: failed writing extracted bytes', e?.message ?? e);
+                }
+            }
         }
         try {
             let idx = 0;
@@ -663,7 +697,203 @@ export async function decodePngToBinary(input, opts = {}) {
                         throw new IncorrectPassphraseError(`Incorrect passphrase (screenshot mode, zstd failed: ` +
                             errMsg +
                             ')');
-                    throw new DataFormatError(`Screenshot mode zstd decompression failed: ` + errMsg);
+                    // Fallback: try reconstituting the image and re-extracting the pixels
+                    try {
+                        if (process.env.ROX_DEBUG)
+                            console.log('DEBUG: decompress failed, attempting cropAndReconstitute fallback');
+                        const reconstructed = await cropAndReconstitute(processedBuf, opts.debugDir);
+                        const raw2 = native.sharpToRaw(reconstructed);
+                        let logicalData2 = Buffer.from(raw2.pixels);
+                        let logicalWidth2 = raw2.width;
+                        let logicalHeight2 = raw2.height;
+                        // find startIdx2 (linear)
+                        let startIdx2 = -1;
+                        const totalPixels2 = (logicalData2.length / 3) | 0;
+                        for (let i2 = 0; i2 <= totalPixels2 - MARKER_START.length; i2++) {
+                            let match2 = true;
+                            for (let mi2 = 0; mi2 < MARKER_START.length && match2; mi2++) {
+                                const offset2 = (i2 + mi2) * 3;
+                                if (logicalData2[offset2] !== MARKER_START[mi2].r ||
+                                    logicalData2[offset2 + 1] !== MARKER_START[mi2].g ||
+                                    logicalData2[offset2 + 2] !== MARKER_START[mi2].b) {
+                                    match2 = false;
+                                }
+                            }
+                            if (match2) {
+                                startIdx2 = i2;
+                                break;
+                            }
+                        }
+                        if (startIdx2 === -1) {
+                            // try 2D scan
+                            let found2D2 = false;
+                            for (let y = 0; y < logicalHeight2 && !found2D2; y++) {
+                                for (let x = 0; x <= logicalWidth2 - MARKER_START.length && !found2D2; x++) {
+                                    let match = true;
+                                    for (let mi = 0; mi < MARKER_START.length && match; mi++) {
+                                        const idx = (y * logicalWidth2 + (x + mi)) * 3;
+                                        if (idx + 2 >= logicalData2.length ||
+                                            logicalData2[idx] !== MARKER_START[mi].r ||
+                                            logicalData2[idx + 1] !== MARKER_START[mi].g ||
+                                            logicalData2[idx + 2] !== MARKER_START[mi].b) {
+                                            match = false;
+                                        }
+                                    }
+                                    if (match) {
+                                        // compute rectangle
+                                        let endX = x + MARKER_START.length - 1;
+                                        let endY = y;
+                                        for (let scanY = y; scanY < logicalHeight2; scanY++) {
+                                            let rowHasData = false;
+                                            for (let scanX = x; scanX < logicalWidth2; scanX++) {
+                                                const scanIdx = (scanY * logicalWidth2 + scanX) * 3;
+                                                if (scanIdx + 2 < logicalData2.length) {
+                                                    const r = logicalData2[scanIdx];
+                                                    const g = logicalData2[scanIdx + 1];
+                                                    const b = logicalData2[scanIdx + 2];
+                                                    const isBackground = (r === 100 && g === 120 && b === 110) ||
+                                                        (r === 0 && g === 0 && b === 0) ||
+                                                        (r >= 50 &&
+                                                            r <= 220 &&
+                                                            g >= 50 &&
+                                                            g <= 220 &&
+                                                            b >= 50 &&
+                                                            b <= 220 &&
+                                                            Math.abs(r - g) < 70 &&
+                                                            Math.abs(r - b) < 70 &&
+                                                            Math.abs(g - b) < 70);
+                                                    if (!isBackground) {
+                                                        rowHasData = true;
+                                                        if (scanX > endX)
+                                                            endX = scanX;
+                                                    }
+                                                }
+                                            }
+                                            if (rowHasData) {
+                                                endY = scanY;
+                                            }
+                                            else if (scanY > y) {
+                                                break;
+                                            }
+                                        }
+                                        const rectWidth = endX - x + 1;
+                                        const rectHeight = endY - y + 1;
+                                        const newDataLen = rectWidth * rectHeight * 3;
+                                        const newData = Buffer.allocUnsafe(newDataLen);
+                                        let writeIdx = 0;
+                                        for (let ry = y; ry <= endY; ry++) {
+                                            for (let rx = x; rx <= endX; rx++) {
+                                                const idx = (ry * logicalWidth2 + rx) * 3;
+                                                newData[writeIdx++] = logicalData2[idx];
+                                                newData[writeIdx++] = logicalData2[idx + 1];
+                                                newData[writeIdx++] = logicalData2[idx + 2];
+                                            }
+                                        }
+                                        logicalData2 = newData;
+                                        logicalWidth2 = rectWidth;
+                                        logicalHeight2 = rectHeight;
+                                        startIdx2 = 0;
+                                        found2D2 = true;
+                                    }
+                                }
+                            }
+                            if (!found2D2)
+                                throw new DataFormatError('Screenshot fallback failed: START not found');
+                        }
+                        // compute endStartPixel2
+                        const curTotalPixels2 = (logicalData2.length / 3) | 0;
+                        const lastLineStart2 = (logicalHeight2 - 1) * logicalWidth2;
+                        const endMarkerStartCol2 = logicalWidth2 - MARKER_END.length;
+                        let endStartPixel2 = -1;
+                        if (lastLineStart2 + endMarkerStartCol2 < curTotalPixels2) {
+                            let matchEnd2 = true;
+                            for (let mi = 0; mi < MARKER_END.length && matchEnd2; mi++) {
+                                const pixelIdx = lastLineStart2 + endMarkerStartCol2 + mi;
+                                if (pixelIdx >= curTotalPixels2) {
+                                    matchEnd2 = false;
+                                    break;
+                                }
+                                const offset = pixelIdx * 3;
+                                if (logicalData2[offset] !== MARKER_END[mi].r ||
+                                    logicalData2[offset + 1] !== MARKER_END[mi].g ||
+                                    logicalData2[offset + 2] !== MARKER_END[mi].b) {
+                                    matchEnd2 = false;
+                                }
+                            }
+                            if (matchEnd2) {
+                                endStartPixel2 =
+                                    lastLineStart2 + endMarkerStartCol2 - startIdx2;
+                                if (process.env.ROX_DEBUG) {
+                                    console.log('DEBUG: Found END marker in fallback at last line');
+                                }
+                            }
+                        }
+                        if (endStartPixel2 === -1) {
+                            if (process.env.ROX_DEBUG) {
+                                console.log('DEBUG: END marker not found in fallback; using end of grid');
+                            }
+                            endStartPixel2 = curTotalPixels2 - startIdx2;
+                        }
+                        const dataPixelCount2 = endStartPixel2 - (MARKER_START.length + 1);
+                        const pixelBytes2 = Buffer.allocUnsafe(dataPixelCount2 * 3);
+                        for (let i2 = 0; i2 < dataPixelCount2; i2++) {
+                            const srcOffset = (startIdx2 + MARKER_START.length + 1 + i2) * 3;
+                            const dstOffset = i2 * 3;
+                            pixelBytes2[dstOffset] = logicalData2[srcOffset];
+                            pixelBytes2[dstOffset + 1] = logicalData2[srcOffset + 1];
+                            pixelBytes2[dstOffset + 2] = logicalData2[srcOffset + 2];
+                        }
+                        // try decompressing fallback payload
+                        const foundPX = pixelBytes2.indexOf(PIXEL_MAGIC);
+                        if (process.env.ROX_DEBUG)
+                            console.log('DEBUG: PIXEL_MAGIC index in fallback:', foundPX);
+                        if (pixelBytes2.length >= PIXEL_MAGIC.length) {
+                            let ii = 0;
+                            const at0 = pixelBytes2
+                                .slice(0, PIXEL_MAGIC.length)
+                                .equals(PIXEL_MAGIC);
+                            if (at0)
+                                ii = PIXEL_MAGIC.length;
+                            else {
+                                const found = pixelBytes2.indexOf(PIXEL_MAGIC);
+                                if (found !== -1)
+                                    ii = found + PIXEL_MAGIC.length;
+                            }
+                            if (ii > 0) {
+                                const version2 = pixelBytes2[ii++];
+                                const nameLen2 = pixelBytes2[ii++];
+                                const payloadLen2 = pixelBytes2.readUInt32BE(ii + nameLen2);
+                                const rawPayload2 = pixelBytes2.slice(ii + nameLen2 + 4, ii + nameLen2 + 4 + payloadLen2);
+                                let payload2 = tryDecryptIfNeeded(rawPayload2, opts.passphrase);
+                                payload2 = await tryDecompress(payload2, (info) => {
+                                    if (opts.onProgress)
+                                        opts.onProgress(info);
+                                });
+                                if (!payload2.slice(0, MAGIC.length).equals(MAGIC)) {
+                                    throw new DataFormatError('Screenshot fallback failed: missing ROX1 magic after decompression');
+                                }
+                                payload2 = payload2.slice(MAGIC.length);
+                                if (opts.files) {
+                                    const unpacked2 = unpackBuffer(payload2, opts.files);
+                                    if (unpacked2) {
+                                        if (opts.onProgress)
+                                            opts.onProgress({ phase: 'done' });
+                                        progressBar?.stop();
+                                        return { files: unpacked2.files, meta: { name } };
+                                    }
+                                }
+                                if (opts.onProgress)
+                                    opts.onProgress({ phase: 'done' });
+                                progressBar?.stop();
+                                return { buf: payload2, meta: { name } };
+                            }
+                        }
+                        throw new DataFormatError('Screenshot mode zstd decompression failed: ' + errMsg);
+                    }
+                    catch (e2) {
+                        // If fallback fails, rethrow original error
+                        throw new DataFormatError(`Screenshot mode zstd decompression failed: ` + errMsg);
+                    }
                 }
                 if (!payload.slice(0, MAGIC.length).equals(MAGIC)) {
                     throw new DataFormatError('Invalid ROX format (pixel mode: missing ROX1 magic after decompression)');

package/dist/utils/encoder.d.ts

@@ -1,2 +1,23 @@
 import { EncodeOptions } from './types.js';
+/**
+ * Encode a buffer or array of buffers into a PNG image (ROX format).
+ *
+ * @param input - The buffer or array of buffers to encode.
+ * @param opts - Optional encoding options.
+ * @returns A Promise that resolves to a PNG Buffer containing the encoded data.
+ *
+ * @example
+ * ```js
+ * import { encodeBinaryToPng } from 'roxify';
+ *
+ * const png = await encodeBinaryToPng(Buffer.from('hello'), {
+ *   mode: 'screenshot',
+ *   name: 'hello.txt',
+ *   compressionLevel: 19,
+ *   outputFormat: 'png',
+ * });
+ *
+ * // write to disk using fs.writeFileSync('out.png', png)
+ * ```
+ */
 export declare function encodeBinaryToPng(input: Buffer | Buffer[], opts?: EncodeOptions): Promise<Buffer>;

package/dist/utils/encoder.js

@@ -6,6 +6,27 @@ import { crc32 } from './crc.js';
 import { colorsToBytes } from './helpers.js';
 import { native } from './native.js';
 import { parallelZstdCompress } from './zstd.js';
+/**
+ * Encode a buffer or array of buffers into a PNG image (ROX format).
+ *
+ * @param input - The buffer or array of buffers to encode.
+ * @param opts - Optional encoding options.
+ * @returns A Promise that resolves to a PNG Buffer containing the encoded data.
+ *
+ * @example
+ * ```js
+ * import { encodeBinaryToPng } from 'roxify';
+ *
+ * const png = await encodeBinaryToPng(Buffer.from('hello'), {
+ *   mode: 'screenshot',
+ *   name: 'hello.txt',
+ *   compressionLevel: 19,
+ *   outputFormat: 'png',
+ * });
+ *
+ * // write to disk using fs.writeFileSync('out.png', png)
+ * ```
+ */
 export async function encodeBinaryToPng(input, opts = {}) {
     let progressBar = null;
     if (opts.showProgress) {

package/dist/utils/inspection.d.ts

@@ -1,8 +1,17 @@
 /**
- * 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
+ * List files stored inside a ROX PNG without fully extracting it.
+ * Returns `null` if no file list could be found.
+ *
+ * @param pngBuf - Buffer containing a PNG file.
+ * @param opts - Options to include sizes.
+ * @returns Promise resolving to an array of file names or objects with sizes.
+ *
+ * @example
+ * ```js
+ * import { listFilesInPng } from 'roxify';
+ * const files = await listFilesInPng(fs.readFileSync('out.png'), { includeSizes: true });
+ * console.log(files);
+ * ```
  */
 export declare function listFilesInPng(pngBuf: Buffer, opts?: {
     includeSizes?: boolean;
@@ -11,7 +20,16 @@ export declare function listFilesInPng(pngBuf: Buffer, opts?: {
     size: number;
 }[] | null>;
 /**
- * Detect if a PNG/ROX buffer contains an encrypted payload (requires passphrase)
- * Returns true if encryption flag indicates AES or XOR.
+ * Check if a PNG contains an encrypted payload requiring a passphrase.
+ *
+ * @param pngBuf - Buffer containing a PNG file.
+ * @returns Promise resolving to `true` if the PNG requires a passphrase.
+ *
+ * @example
+ * ```js
+ * import { hasPassphraseInPng } from 'roxify';
+ * const needPass = await hasPassphraseInPng(fs.readFileSync('out.png'));
+ * console.log('needs passphrase?', needPass);
+ * ```
  */
 export declare function hasPassphraseInPng(pngBuf: Buffer): Promise<boolean>;

package/dist/utils/inspection.js

@@ -6,10 +6,19 @@ import { PassphraseRequiredError } from './errors.js';
 import { native } from './native.js';
 import { cropAndReconstitute } from './reconstitution.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
+ * List files stored inside a ROX PNG without fully extracting it.
+ * Returns `null` if no file list could be found.
+ *
+ * @param pngBuf - Buffer containing a PNG file.
+ * @param opts - Options to include sizes.
+ * @returns Promise resolving to an array of file names or objects with sizes.
+ *
+ * @example
+ * ```js
+ * import { listFilesInPng } from 'roxify';
+ * const files = await listFilesInPng(fs.readFileSync('out.png'), { includeSizes: true });
+ * console.log(files);
+ * ```
  */
 export async function listFilesInPng(pngBuf, opts = {}) {
     try {
@@ -412,8 +421,17 @@ async function getFileSizesFromPng(pngBuf) {
     return null;
 }
 /**
- * Detect if a PNG/ROX buffer contains an encrypted payload (requires passphrase)
- * Returns true if encryption flag indicates AES or XOR.
+ * Check if a PNG contains an encrypted payload requiring a passphrase.
+ *
+ * @param pngBuf - Buffer containing a PNG file.
+ * @returns Promise resolving to `true` if the PNG requires a passphrase.
+ *
+ * @example
+ * ```js
+ * import { hasPassphraseInPng } from 'roxify';
+ * const needPass = await hasPassphraseInPng(fs.readFileSync('out.png'));
+ * console.log('needs passphrase?', needPass);
+ * ```
  */
 export async function hasPassphraseInPng(pngBuf) {
     try {

package/dist/utils/reconstitution.d.ts

@@ -1 +1,8 @@
+/**
+ * Reconstitute a PNG buffer by cropping and reconstructing the image.
+ *
+ * @param input - Buffer containing the PNG image.
+ * @param debugDir - Optional directory to write debug images.
+ * @returns Promise resolving to the reconstituted PNG buffer.
+ */
 export declare function cropAndReconstitute(input: Buffer, debugDir?: string): Promise<Buffer>;

package/dist/utils/reconstitution.js

@@ -1,4 +1,34 @@
+import { writeFileSync } from 'fs';
+import { join } from 'path';
 import { native } from './native.js';
+/**
+ * Reconstitute a PNG buffer by cropping and reconstructing the image.
+ *
+ * @param input - Buffer containing the PNG image.
+ * @param debugDir - Optional directory to write debug images.
+ * @returns Promise resolving to the reconstituted PNG buffer.
+ */
 export async function cropAndReconstitute(input, debugDir) {
-    return Buffer.from(native.cropAndReconstitute(input));
+    const out = Buffer.from(native.cropAndReconstitute(input));
+    if (debugDir) {
+        try {
+            const meta = native.sharpMetadata(input);
+            const doubled = native.sharpResizeImage(input, meta.width * 2, meta.height * 2, 'nearest');
+            console.log('DEBUG: writing doubled.png to', debugDir);
+            writeFileSync(join(debugDir, 'doubled.png'), Buffer.from(doubled));
+        }
+        catch (e) {
+            console.log('DEBUG: failed to write doubled.png', e?.message ?? e);
+        }
+        try {
+            console.log('DEBUG: writing reconstructed.png and reconstructed-pixels.bin to', debugDir);
+            writeFileSync(join(debugDir, 'reconstructed.png'), out);
+            const raw = native.sharpToRaw(out);
+            writeFileSync(join(debugDir, 'reconstructed-pixels.bin'), Buffer.from(raw.pixels));
+        }
+        catch (e) {
+            console.log('DEBUG: failed to write reconstructed artifacts', e?.message ?? e);
+        }
+    }
+    return out;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roxify",
-  "version": "1.5.2",
+  "version": "1.5.4",
   "description": "Ultra-lightweight PNG steganography with native Rust acceleration. Encode binary data into PNG images with zstd compression.",
   "type": "module",
   "main": "dist/index.js",
@@ -27,8 +27,9 @@
     "build:native:windows": "cargo build --release --lib --target x86_64-pc-windows-msvc && cp target/x86_64-pc-windows-msvc/release/roxify_native.dll libroxify_native-x86_64-pc-windows-msvc.dll",
     "build:cli": "cargo build --release --bin roxify_native && cp target/release/roxify_native dist/roxify-cli",
     "build:all": "npm run build:native && npm run build && npm run build:cli",
+    "build:cross": "node scripts/build-all-platforms.js && npm run build && npm run build:cli",
     "postbuild:native": "node scripts/copy-native.js",
-    "prepublishOnly": "npm run build:all",
+    "prepublishOnly": "npm run build:cross",
     "test": "npm run build && node test/run-all-tests.js",
     "cli": "node dist/cli.js"
   },