PuttyPNG

PuttyPNG.encode(input, options?)

Hides input (a string, plain object, Uint8Array, ArrayBuffer, or File/Blob) inside a PNG.

Result: { dataUrl, blob, width, height, depth, compressed, encrypted, bytesHidden, capacityBytes, usedPercent }

const png = await PuttyPNG.encode("hello", { password: "s3cret", depth: "subtle" });
document.querySelector("img").src = png.dataUrl;   // show it
// png.blob is a PNG Blob you can upload, download, or copy to the clipboard

PuttyPNG.decode(source, options?)

source may be a File/Blob, an <img>, a <canvas>, an ImageData, or a data-URL / URL string.

Result: { type, name, mime, bytes, text?, json?, tag, encrypted, compressed, depth, width, height }. type is "text", "json", or "binary".

const result = await PuttyPNG.decode(file);
if (result.type === "binary") PuttyPNG.download(result);
else console.log(result.text, result.json);

PuttyPNG.peek(source)

Reads the header and the plaintext developer tag without decrypting. Returns { isPuttyPNG: false } for anything that is not a PuttyPNG.

const info = await PuttyPNG.peek(file);
if (info.isPuttyPNG && info.tag === "myapp v2") { /* it's ours */ }

PuttyPNG.download(result, filename?) · PuttyPNG.passwordPrompt

download() saves a decoded result (or a raw Blob) to disk. passwordPrompt is the override point for password entry. It defaults to the browser's native prompt(). Replace it with your own UI (see Custom prompt).

Fixed header: 18 bytes, always at 1-1-1 depth (first 48 opaque pixels)

Body: at the flag-declared depth

[dev tag][outer metadata][payload]

The outer metadata is empty unless encrypted, in which case it holds the (plaintext) crypto parameters: { enc, kdf, iterations, salt, iv }. The payload is the processed inner container.

Inner container (protected content)

[uint16 metadata length][metadata JSON: {name, type, mime}][data bytes]

Because the inner container lives inside the compress/encrypt envelope, an encrypted PuttyPNG reveals no filename or type.

Depths, opacity & transparency

Standard packs 3 bits into R, 2 into G, 3 into B, one byte per pixel. Subtle uses one bit per channel, three bits per pixel, invisible even on flat art. Only alpha = 255 pixels carry data; alpha is never modified.

Transparency is hardened. Semi-transparent, anti-aliased fringe pixels (alpha 1 to 254) are the ones platforms silently rewrite, so a custom cover is snapped to binary alpha: every fringe pixel becomes fully opaque, while genuinely transparent (alpha 0) regions are kept. No data-bearing pixel ever borders fractional alpha, so a lossless round-trip, or a flatten onto any background, leaves every hidden byte intact.

Order of operations

Encode: build inner container → gzip (if it helps) → encrypt (if a password is given) → CRC32 → embed. Decode reverses it, and the CRC is checked before any password is requested.

Versioning

The version byte bumps only on a breaking byte-layout change. An old engine refuses a newer PuttyPNG (PTY-E01) instead of emitting garbage. Backwards-compatible growth happens by adding optional keys to the metadata JSON, which old decoders ignore.

Transparent vs solid, and a flattening caveat

By default the CD's corners are transparent, so it drops cleanly onto any background. Turn on solidBackground to fill them with a soft gradient. That makes the disc fully opaque, which both shrinks it (more room for data) and makes it survive being flattened. This matters: if a platform composites a transparent PuttyPNG onto an opaque background, the once-transparent pixels become opaque and shift the data's pixel indexing, so it will not decode. Use a transparent cover only where the image is kept with its alpha intact (lossless PNG); use a solid background (or the noise style) for anywhere that might flatten it.

Call the engine directly

No widgets. Encode and decode in your own flow.

// Export whatever your app holds:
const save = { level: 7, score: 9001, items: ["sword"] };
const png = await PuttyPNG.encode(save, { name: "save.json" });
uploadOrShare(png.blob);

// Import from anywhere you already have the image:
const result = await PuttyPNG.decode(pastedImageElement);
applySave(result.json);

Your own cover art

Hand PuttyPNG a picture to hide the data in. By default it is resampled (high quality) to the smallest size that still fits the data. The source resolution is ignored, so a huge photo will not make a huge PuttyPNG. Raise minSize or set a fixed size to keep the art larger; use keepRatio to preserve the original (non-square) shape.

// Smallest square that fits, cropped, fringe auto-hardened:
await PuttyPNG.encode(data, { cover: "logo.png" });

// Keep the picture's original shape, and don't shrink below 256px:
await PuttyPNG.encode(data, { cover: "banner.png", coverFit: "keepRatio", minSize: 256 });

// Lock a fixed size regardless of data:
await PuttyPNG.encode(data, { cover: "logo.png", size: 512 });

Generate your own cover in JS

The CD style is a canvas drawn in code. You can do the same: draw an ImageData (or a canvas / data-URL) and pass it as the cover. PuttyPNG hardens any transparency and hides the data in the opaque pixels. Use the built-in "cd" style for a ready-made disc.

// Built-in reflective CD with a label + a burned-in imprint:
await PuttyPNG.encode(data, { coverStyle: "cd", label: "My Album", imprint: "logo.png" });

// ...or draw your own cover on a canvas and hand it over:
const c = document.createElement("canvas"); c.width = c.height = 256;
const x = c.getContext("2d");
const g = x.createLinearGradient(0, 0, 256, 256);
g.addColorStop(0, "#1b2a4a"); g.addColorStop(1, "#c96f52");
x.fillStyle = g; x.fillRect(0, 0, 256, 256);
await PuttyPNG.encode(data, { cover: c.toDataURL("image/png") });

Recognize your own PuttyPNGs with the dev tag

Stamp a plaintext tag on export, then peek() on import to route it. No password is needed to know it is yours. Great for versioning an app's own format (a chess game, a doc editor, ...).

await PuttyPNG.encode(move, { tag: "chess v3", password: userPw });

// Later, on any dropped image:
const info = await PuttyPNG.peek(image);
if (!info.isPuttyPNG || !/^chess /.test(info.tag)) return ignore();
const move = (await PuttyPNG.decode(image)).json;   // prompts for the password

Encryption tiers: good, better, best

// Better: a fixed page key (anyone reading your source can find it)
const PAGE_KEY = "our-club-2026";
await PuttyPNG.encode(data, { password: PAGE_KEY });

// Best: a real per-user secret
await PuttyPNG.encode(data, { password: await askUserForPassword() });

PuttyPNG.passwordPrompt = function (context) {
  return new Promise(function (resolve) {
    const wrap = document.createElement("div");
    wrap.style.cssText =
      "position:fixed;inset:0;background:rgba(0,0,0,.45);display:flex;" +
      "align-items:center;justify-content:center;z-index:9999";
    wrap.innerHTML =
      "<form style='background:#fff;border-radius:14px;padding:22px;width:300px;" +
      "font-family:system-ui;box-shadow:0 20px 60px rgba(0,0,0,.3)'>" +
      "<h3 style='margin:0 0 10px'>Password</h3>" +
      "<p style='margin:0 0 12px;color:#666;font-size:14px'>" + (context.message || "") + "</p>" +
      "<input type='password' autofocus style='width:100%;padding:10px;border:1px solid #ccc;" +
      "border-radius:8px;font-size:15px'>" +
      "<div style='display:flex;gap:8px;justify-content:flex-end;margin-top:14px'>" +
      "<button type='button' data-x style='padding:8px 14px'>Cancel</button>" +
      "<button style='padding:8px 14px;background:#111;color:#fff;border:none;" +
      "border-radius:999px'>Open</button></div></form>";
    const input = wrap.querySelector("input");
    function close(value) { wrap.remove(); resolve(value); }
    wrap.querySelector("[data-x]").onclick = function () { close(null); };
    wrap.querySelector("form").onsubmit = function (e) { e.preventDefault(); close(input.value); };
    document.body.appendChild(wrap);
    input.focus();
  });
};