roxify 1.0.0 → 1.1.1

package/README.md

@@ -1,368 +1,97 @@
-# RoxCompressor Transform
-
-> Encode binary data into PNG images and decode them back. Fast, efficient, with optional encryption.
+# roxify
 
 [![npm version](https://img.shields.io/npm/v/roxify.svg)](https://www.npmjs.com/package/roxify)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-
-## Features
 
-- 🚀 **Fast**: Optimized Brotli compression (quality 1 by default) — encode 3.8 MB in ~1 second
-- 🔒 **Secure**: AES-256-GCM encryption support with PBKDF2 key derivation
-- 🎨 **Multiple modes**: Compact, chunk, pixel, and screenshot modes
-- 📦 **CLI & API**: Use as command-line tool or JavaScript library
-- 🔄 **Lossless**: Perfect roundtrip encoding/decoding
-- 📊 **Efficient**: Typically 20-30% of original size with compression
-- 📖 **Full TSDoc**: Complete TypeScript documentation
+Encode binary data into PNG images and decode them back. Supports CLI and programmatic API (Node.js ESM).
 
-## Documentation
+Roxify is a compact, color-based alternative to QR codes, designed specifically for digital-only use (not for printing). It encodes data using color channels (rather than monochrome patterns) for higher density, and is optimized for decoding from approximate screenshots — including nearest-neighbour resize/stretch and solid or gradient backgrounds. It is not intended for printed media and is not resilient to lossy compression or heavy image filtering.
 
-- 📘 **[CLI Documentation](./CLI.md)** - Complete command-line usage guide
-- 📗 **[JavaScript SDK](./JAVASCRIPT_SDK.md)** - Programmatic API reference with examples
-- 📙 **[Quick Start](#quick-start)** - Get started in 2 minutes
+Roxified PNGs are often more space-efficient than ZIP archives for similar payloads and provide a visual indication of the embedded data size.
 
 ## Installation
 
-### As CLI tool (npx)
-
-No installation needed! Use directly with npx:
-
-```bash
-  npx rox encode input.zip output.png
-  npx rox decode output.png original.zip
-```
-
-### As library
-
 ```bash
 npm install roxify
 ```
 
 ## CLI Usage
 
-### Quick Start
-
 ```bash
-# Encode a file
-  npx rox encode document.pdf document.png
-
-# Decode it back
-  npx rox decode document.png document.pdf
-
-# With encryption
-  npx rox encode secret.zip secret.png -p mypassword
-  npx rox decode secret.png secret.zip -p mypassword
-```
-
-### CLI Commands
-
-#### `encode` - Encode file to PNG
+npx rox encode <inputName>.ext (<outputName>.png)
 
-```bash
-  npx rox encode <input> [output] [options]
+npx rox decode <inputName>.png (<outputName>.ext)
 ```
 
-**Options:**
-
-- `-p, --passphrase <pass>` - Encrypt with passphrase (AES-256-GCM)
-- `-m, --mode <mode>` - Encoding mode: `compact|chunk|pixel|screenshot` (default: `screenshot`)
-- `-q, --quality <0-11>` - Brotli compression quality (default: `1`)
-  - `0` = fastest, largest
-  - `11` = slowest, smallest
-- `-e, --encrypt <type>` - Encryption: `auto|aes|xor|none` (default: `aes` if passphrase)
-- `--no-compress` - Disable compression
-- `-o, --output <path>` - Output file path
-
-**Examples:**
-
-```bash
-# Basic encoding
-  npx rox encode data.bin output.png
-
-# Fast compression for large files
-  npx rox encode large-video.mp4 output.png -q 0
+If no output name is provided:
 
-# High compression for small files
-  npx rox encode config.json output.png -q 11
+- Encoding: output defaults to `<inputName>.png`.
+- Decoding: if the image contains the original filename it will be restored; otherwise the output will be `decoded.bin`.
 
-# With encryption
-  npx rox encode secret.pdf secure.png -p "my secure password"
+**Commands:**
 
-# Compact mode (smallest PNG)
-  npx rox encode data.bin tiny.png -m compact
-
-# Screenshot mode (recommended, looks like a real image)
-  npx rox encode archive.tar.gz screenshot.png -m screenshot
-```
-
-#### `decode` - Decode PNG to file
-
-```bash
-  npx rox decode <input> [output] [options]
-```
+- `encode <input> [output]` — Encode file to PNG
+- `decode <input> [output]` — Decode PNG to file
 
 **Options:**
 
-- `-p, --passphrase <pass>` - Decryption passphrase
-- `-o, --output <path>` - Output file path (auto-detected from metadata if not provided)
-
-**Examples:**
+- `-p, --passphrase <pass>` — Encrypt with AES-256-GCM
+- `-m, --mode <mode>` — Encoding mode: `screenshot` (default), `pixel`, `compact`, `chunk`
+- `-q, --quality <0-11>` — Brotli compression quality (default: 11)
+- `--no-compress` — Disable compression
+- `-v, --verbose` — Show detailed errors
 
-```bash
-# Basic decoding
-  npx rox decode encoded.png output.bin
-
-# Auto-detect filename from metadata
-  npx rox decode encoded.png
-
-# With decryption
-  npx rox decode encrypted.png output.pdf -p "my secure password"
-```
+Run `npx rox help` for full options.
 
-## JavaScript API
+## API Usage
 
-### Basic Usage
-
-```typescript
+```js
 import { encodeBinaryToPng, decodePngToBinary } from 'roxify';
-import { readFileSync, writeFileSync } from 'fs';
-
-// Encode
-const input = readFileSync('input.zip');
-const png = await encodeBinaryToPng(input, {
-  mode: 'screenshot',
-  name: 'input.zip',
-});
-writeFileSync('output.png', png);
-
-// Decode
-const encoded = readFileSync('output.png');
-const result = await decodePngToBinary(encoded);
-writeFileSync(result.meta?.name || 'output.bin', result.buf);
-```
-
-### With Encryption
-
-```typescript
-// Encode with AES-256-GCM
-const png = await encodeBinaryToPng(input, {
-  mode: 'screenshot',
-  passphrase: 'my-secret-password',
-  encrypt: 'aes',
-  name: 'secret.zip',
-});
 
-// Decode with passphrase
-const result = await decodePngToBinary(encoded, {
-  passphrase: 'my-secret-password',
-});
-```
-
-### Fast Compression
-
-```typescript
-// Optimize for speed (recommended for large files)
-const png = await encodeBinaryToPng(largeBuffer, {
+const data = Buffer.from('Hello world');
+const png = await encodeBinaryToPng(data, {
   mode: 'screenshot',
-  brQuality: 0, // Fastest
-  name: 'large-file.bin',
+  name: 'message.txt',
 });
 
-// Optimize for size (recommended for small files)
-const png = await encodeBinaryToPng(smallBuffer, {
-  mode: 'compact',
-  brQuality: 11, // Best compression
-  name: 'config.json',
-});
-```
-
-### Encoding Modes
-
-#### `screenshot` (Recommended)
-
-Encodes data as RGB pixel values, optimized for screenshot-like appearance. Best balance of size and compatibility.
-
-```typescript
-const png = await encodeBinaryToPng(data, { mode: 'screenshot' });
-```
-
-#### `compact` (Smallest)
-
-Minimal 1x1 PNG with data in custom chunk. Fastest and smallest.
-
-```typescript
-const png = await encodeBinaryToPng(data, { mode: 'compact' });
+const { buf, meta } = await decodePngToBinary(png);
+console.log(buf.toString('utf8'));
+console.log(meta?.name);
 ```
 
-#### `pixel`
+**API:**
 
-Encodes data as RGB pixel values without screenshot optimization.
-
-```typescript
-const png = await encodeBinaryToPng(data, { mode: 'pixel' });
-```
-
-#### `chunk`
-
-Standard PNG with data in custom rXDT chunk.
-
-```typescript
-const png = await encodeBinaryToPng(data, { mode: 'chunk' });
-```
-
-## API Reference
-
-### `encodeBinaryToPng(input, options)`
-
-Encodes binary data into a PNG image.
-
-**Parameters:**
-
-- `input: Buffer` - The binary data to encode
-- `options?: EncodeOptions` - Encoding options
-
-**Returns:** `Promise<Buffer>` - The encoded PNG
+- `encodeBinaryToPng(input: Buffer, opts?: EncodeOptions): Promise<Buffer>`
+- `decodePngToBinary(pngBuf: Buffer): Promise<{ buf: Buffer, meta?: { name?: string } }>`
 
 **Options:**
 
-```typescript
-interface EncodeOptions {
-  // Compression algorithm ('br' = Brotli, 'none' = no compression)
-  compression?: 'br' | 'none';
-
-  // Passphrase for encryption
-  passphrase?: string;
-
-  // Original filename to embed
-  name?: string;
+- `mode` — `'screenshot'` | `'pixel'` | `'compact'` | `'chunk'` (default: `'screenshot'`)
+- `name` — Original filename (embedded as metadata)
+- `passphrase` — Encryption passphrase (uses AES-256-GCM)
+- `compression` — `'br'` | `'none'` (default: `'br'`)
+- `brQuality` — Brotli quality 0-11 (default: 4)
 
-  // Encoding mode
-  mode?: 'compact' | 'chunk' | 'pixel' | 'screenshot';
-
-  // Encryption method
-  encrypt?: 'auto' | 'aes' | 'xor' | 'none';
-
-  // Output format
-  output?: 'auto' | 'png' | 'rox';
-
-  // Include filename in metadata (default: true)
-  includeName?: boolean;
-
-  // Brotli quality 0-11 (default: 1)
-  brQuality?: number;
-}
-```
-
-### `decodePngToBinary(pngBuf, options)`
-
-Decodes a PNG image back to binary data.
-
-**Parameters:**
-
-- `pngBuf: Buffer` - The PNG image to decode
-- `options?: DecodeOptions` - Decoding options
-
-**Returns:** `Promise<DecodeResult>` - The decoded data and metadata
-
-**Options:**
-
-```typescript
-interface DecodeOptions {
-  // Passphrase for decryption
-  passphrase?: string;
-}
-```
+## Example: Express Endpoint
 
-**Result:**
+```js
+import express from 'express';
+import { encodeBinaryToPng } from 'roxify';
 
-```typescript
-interface DecodeResult {
-  // Decoded binary data
-  buf: Buffer;
-
-  // Extracted metadata
-  meta?: {
-    // Original filename
-    name?: string;
-  };
-}
-```
-
-## Performance Tips
-
-### For Large Files (>10 MB)
-
-```bash
-# Use quality 0 for fastest encoding
-npx rox encode large.bin output.png -q 0
-```
-
-```typescript
-const png = await encodeBinaryToPng(largeFile, {
-  mode: 'screenshot',
-  brQuality: 0, // 10-20x faster than default
+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);
 });
+app.listen(3000);
 ```
 
-### For Small Files (<1 MB)
+## Requirements
 
-```bash
-# Use quality 11 for best compression
-npx rox encode small.json output.png -q 11 -m compact
-```
-
-```typescript
-const png = await encodeBinaryToPng(smallFile, {
-  mode: 'compact',
-  brQuality: 11, // Best compression ratio
-});
-```
-
-### Benchmark Results
-
-File: 3.8 MB binary
-
-- **Quality 0**: ~500-800ms, output ~1.2 MB
-- **Quality 1** (default): ~1-2s, output ~800 KB
-- **Quality 5**: ~8-12s, output ~750 KB
-- **Quality 11**: ~20-30s, output ~720 KB
-
-## Error Handling
-
-```typescript
-try {
-  const result = await decodePngToBinary(encoded, {
-    passphrase: 'wrong-password',
-  });
-} catch (err) {
-  if (err.message.includes('Incorrect passphrase')) {
-    console.error('Wrong password!');
-  } else if (err.message.includes('Invalid ROX format')) {
-    console.error('Not a valid RoxCompressor PNG');
-  } else {
-    console.error('Decode failed:', err.message);
-  }
-}
-```
-
-## Security
-
-- **AES-256-GCM**: Authenticated encryption with 100,000 PBKDF2 iterations
-- **XOR cipher**: Simple obfuscation (not cryptographically secure)
-- **No encryption**: Data is compressed but not encrypted
-
-⚠️ **Warning**: Use strong passphrases for sensitive data. The `xor` encryption mode is not secure and should only be used for obfuscation.
+- Node.js 18+ (ESM)
+- Native dependencies: `sharp` (auto-installed)
 
 ## License
 
-MIT © RoxCompressor
-
-## Contributing
-
-Contributions welcome! Please open an issue or PR on GitHub.
-
-## Links
-
-- [GitHub Repository](https://github.com/RoxasYTB/RoxCompressor)
-- [npm Package](https://www.npmjs.com/package/roxify)
-- [Report Issues](https://github.com/RoxasYTB/RoxCompressor/issues)
+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.

package/dist/cli.js

@@ -173,7 +173,7 @@ async function decodeCommand(args) {
         catch (e) {
             console.log('Could not generate reconst PNG:', e.message);
         }
-        console.log(`Reading: ${resolvedInputPath}`);
+        console.log(`Reading: ${resolvedInputPath.replace('_reconst.png', '.png')}`);
         const options = {};
         if (parsed.passphrase) {
             options.passphrase = parsed.passphrase;

package/dist/index.js

@@ -108,6 +108,19 @@ async function loadRaw(imgInput) {
     return { data, info };
 }
 export async function cropAndReconstitute(input) {
+    async function loadRaw(imgInput) {
+        const { data, info } = await sharp(imgInput)
+            .ensureAlpha()
+            .raw()
+            .toBuffer({ resolveWithObject: true });
+        return { data, info };
+    }
+    function idxFor(x, y, width) {
+        return (y * width + x) * 4;
+    }
+    function eqRGB(a, b) {
+        return a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
+    }
     const { data, info } = await loadRaw(input);
     const w = info.width;
     const h = info.height;
@@ -183,8 +196,8 @@ export async function cropAndReconstitute(input) {
     const sy1 = Math.min(startPoint.y, endPoint.y);
     const sx2 = Math.max(startPoint.x, endPoint.x);
     const sy2 = Math.max(startPoint.y, endPoint.y);
-    const cropW = sx2 - sx1;
-    const cropH = sy2 - sy1;
+    const cropW = sx2 - sx1 + 1;
+    const cropH = sy2 - sy1 + 1;
     if (cropW <= 0 || cropH <= 0)
         throw new Error('Invalid crop dimensions');
     const cropped = await sharp(input)
@@ -212,19 +225,84 @@ export async function cropAndReconstitute(input) {
                 return false;
         return true;
     }
-    const compressedLines = [];
+    const newWidth = cw;
+    const newHeight = ch + 1;
+    const out = Buffer.alloc(newWidth * newHeight * 4, 0);
+    for (let i = 0; i < out.length; i += 4)
+        out[i + 3] = 255;
     for (let y = 0; y < ch; y++) {
+        for (let x = 0; x < cw; x++) {
+            const srcI = ((y * cw + x) * 4) | 0;
+            const dstI = ((y * newWidth + x) * 4) | 0;
+            out[dstI] = cdata[srcI];
+            out[dstI + 1] = cdata[srcI + 1];
+            out[dstI + 2] = cdata[srcI + 2];
+            out[dstI + 3] = cdata[srcI + 3];
+        }
+    }
+    if (cw >= 3) {
+        const targetY = ch - 1;
+        for (let x = cw - 3; x < cw; x++) {
+            const i = ((targetY * newWidth + x) * 4) | 0;
+            out[i] = 0;
+            out[i + 1] = 0;
+            out[i + 2] = 0;
+            out[i + 3] = 255;
+        }
+    }
+    else {
+        const targetY = ch - 1;
+        for (let x = 0; x < cw; x++) {
+            const i = ((targetY * newWidth + x) * 4) | 0;
+            out[i] = 0;
+            out[i + 1] = 0;
+            out[i + 2] = 0;
+            out[i + 3] = 255;
+        }
+    }
+    const lastY = ch;
+    for (let x = 0; x < newWidth; x++) {
+        const i = ((lastY * newWidth + x) * 4) | 0;
+        out[i] = 0;
+        out[i + 1] = 0;
+        out[i + 2] = 0;
+        out[i + 3] = 255;
+    }
+    if (newWidth >= 3) {
+        const bgrStart = newWidth - 3;
+        let i = ((lastY * newWidth + bgrStart) * 4) | 0;
+        out[i] = 0;
+        out[i + 1] = 0;
+        out[i + 2] = 255;
+        out[i + 3] = 255;
+        i = ((lastY * newWidth + bgrStart + 1) * 4) | 0;
+        out[i] = 0;
+        out[i + 1] = 255;
+        out[i + 2] = 0;
+        out[i + 3] = 255;
+        i = ((lastY * newWidth + bgrStart + 2) * 4) | 0;
+        out[i] = 255;
+        out[i + 1] = 0;
+        out[i + 2] = 0;
+        out[i + 3] = 255;
+    }
+    function getPixel(x, y) {
+        const i = ((y * newWidth + x) * 4) | 0;
+        return [out[i], out[i + 1], out[i + 2], out[i + 3]];
+    }
+    const compressedLines = [];
+    for (let y = 0; y < newHeight; y++) {
         const line = [];
         let x = 0;
-        while (x < cw) {
-            const current = cat(x, y);
+        while (x < newWidth) {
+            const current = getPixel(x, y);
             if (current[0] === 0 && current[1] === 0 && current[2] === 0) {
                 x++;
                 continue;
             }
             line.push(current);
             let nx = x + 1;
-            while (nx < cw && eq(cat(nx, y), current))
+            while (nx < newWidth && eq(getPixel(nx, y), current))
                 nx++;
             x = nx;
         }
@@ -246,90 +324,25 @@ export async function cropAndReconstitute(input) {
             .png()
             .toBuffer();
     }
-    const newWidth = Math.max(...compressedLines.map((l) => l.length));
-    const newHeight = compressedLines.length + 1;
-    const out = Buffer.alloc(newWidth * newHeight * 4, 0);
-    for (let i = 0; i < out.length; i += 4)
-        out[i + 3] = 255;
+    const finalWidth = Math.max(...compressedLines.map((l) => l.length));
+    const finalHeight = compressedLines.length;
+    const finalOut = Buffer.alloc(finalWidth * finalHeight * 4, 0);
+    for (let i = 0; i < finalOut.length; i += 4)
+        finalOut[i + 3] = 255;
     for (let y = 0; y < compressedLines.length; y++) {
         const line = compressedLines[y];
-        const isSecondToLast = y === compressedLines.length - 1;
-        const startX = 0;
-        const effectiveLength = isSecondToLast
-            ? Math.max(0, line.length - 3)
-            : line.length;
-        for (let x = 0; x < effectiveLength; x++) {
-            const i = ((y * newWidth + startX + x) * 4) | 0;
-            out[i] = line[x][0];
-            out[i + 1] = line[x][1];
-            out[i + 2] = line[x][2];
-            out[i + 3] = line[x][3] === 0 ? 255 : line[x][3];
-        }
-        if (isSecondToLast) {
-            for (let x = effectiveLength; x < Math.min(effectiveLength + 3, newWidth); x++) {
-                const i = ((y * newWidth + x) * 4) | 0;
-                out[i] = 0;
-                out[i + 1] = 0;
-                out[i + 2] = 0;
-                out[i + 3] = 255;
-            }
-        }
-    }
-    const secondToLastY = newHeight - 2;
-    let secondToLastIsBlack = true;
-    for (let x = 0; x < newWidth; x++) {
-        const i = ((secondToLastY * newWidth + x) * 4) | 0;
-        if (out[i] !== 0 || out[i + 1] !== 0 || out[i + 2] !== 0) {
-            secondToLastIsBlack = false;
-            break;
-        }
-    }
-    let finalHeight = newHeight;
-    let finalOut = out;
-    if (secondToLastIsBlack) {
-        finalHeight = newHeight - 1;
-        finalOut = Buffer.alloc(newWidth * finalHeight * 4, 0);
-        for (let i = 0; i < finalOut.length; i += 4)
-            finalOut[i + 3] = 255;
-        for (let y = 0; y < newHeight - 2; y++) {
-            for (let x = 0; x < newWidth; x++) {
-                const srcI = ((y * newWidth + x) * 4) | 0;
-                const dstI = ((y * newWidth + x) * 4) | 0;
-                finalOut[dstI] = out[srcI];
-                finalOut[dstI + 1] = out[srcI + 1];
-                finalOut[dstI + 2] = out[srcI + 2];
-                finalOut[dstI + 3] = out[srcI + 3];
-            }
+        const isLastLine = y === compressedLines.length - 1;
+        const startX = isLastLine ? finalWidth - line.length : 0;
+        for (let x = 0; x < line.length; x++) {
+            const i = ((y * finalWidth + startX + x) * 4) | 0;
+            finalOut[i] = line[x][0];
+            finalOut[i + 1] = line[x][1];
+            finalOut[i + 2] = line[x][2];
+            finalOut[i + 3] = line[x][3] === 0 ? 255 : line[x][3];
         }
     }
-    const lastY = finalHeight - 1;
-    for (let x = 0; x < newWidth; x++) {
-        const i = ((lastY * newWidth + x) * 4) | 0;
-        finalOut[i] = 0;
-        finalOut[i + 1] = 0;
-        finalOut[i + 2] = 0;
-        finalOut[i + 3] = 255;
-    }
-    if (newWidth >= 3) {
-        const bgrStart = newWidth - 3;
-        let i = ((lastY * newWidth + bgrStart) * 4) | 0;
-        finalOut[i] = 0;
-        finalOut[i + 1] = 0;
-        finalOut[i + 2] = 255;
-        finalOut[i + 3] = 255;
-        i = ((lastY * newWidth + bgrStart + 1) * 4) | 0;
-        finalOut[i] = 0;
-        finalOut[i + 1] = 255;
-        finalOut[i + 2] = 0;
-        finalOut[i + 3] = 255;
-        i = ((lastY * newWidth + bgrStart + 2) * 4) | 0;
-        finalOut[i] = 255;
-        finalOut[i + 1] = 0;
-        finalOut[i + 2] = 0;
-        finalOut[i + 3] = 255;
-    }
     return sharp(finalOut, {
-        raw: { width: newWidth, height: finalHeight, channels: 4 },
+        raw: { width: finalWidth, height: finalHeight, channels: 4 },
     })
         .png()
         .toBuffer();
@@ -442,7 +455,7 @@ export async function encodeBinaryToPng(input, opts = {}) {
         const spaceInLastRow = pixelsInLastRow === 0 ? logicalWidth : logicalWidth - pixelsInLastRow;
         const needsExtraRow = spaceInLastRow < MARKER_END.length;
         const logicalHeight = needsExtraRow ? dataRows + 1 : dataRows;
-        const scale = 1;
+        const scale = 2;
         const width = logicalWidth * scale;
         const height = logicalHeight * scale;
         const raw = Buffer.alloc(width * height * bytesPerPixel);
@@ -489,10 +502,10 @@ export async function encodeBinaryToPng(input, opts = {}) {
             raw: { width, height, channels: 3 },
         })
             .png({
-            compressionLevel: 0,
+            compressionLevel: 9,
             palette: false,
-            effort: 1,
-            adaptiveFiltering: false,
+            effort: 10,
+            adaptiveFiltering: true,
         })
             .toBuffer();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roxify",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Encode binary data into PNG images and decode them back. Supports CLI and programmatic API (Node.js ESM).",
   "type": "module",
   "main": "dist/index.js",