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

On its own the CD has transparent corners, so it drops cleanly onto any background. Turn on solidBackground and the disc is set in a light grey jewel case instead, lying on white paper that runs to the corners. Every pixel of the square becomes opaque, so the whole square carries data (a 256px cover holds 65,425 bytes rather than 46,635) and the picture survives being flattened. The page turns it on by default, and the Solid switch under the Make button turns it off: the word reads Solid while it is on and See-thru while it is not. 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();
  });
};