pngjs 6.0.0: PNG.sync.read

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify PNG.sync.read in pkg:npm/pngjs@6.0.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/pngjs@6.0.0
Demonstrate these symbols/APIs:
  - PNG.sync.read

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:f72599b51e1ee1957f5532e8229ce1550b5845876b659ae62dd9a0bacf3802fe","contract":["PNG.sync.read synchronously parses a valid PNG buffer into a PNG instance with width, height, and RGBA data buffer matching the source image dimensions","PNG.sync.read parses image pixel data accurately, preserving individual RGBA channel values","PNG.sync.read accepts optional configuration options such as skipRescale","PNG.sync.read throws an error when provided with an invalid or corrupted PNG buffer"],"goal":"verify PNG.sync.read in pkg:npm/pngjs@6.0.0","kind":"HOW","packages":["pkg:npm/pngjs@6.0.0"],"schemaVersion":1,"symbols":["PNG.sync.read"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/pngjs@6.0.0"],"schemaVersion":1,"subject":"pkg:npm/pngjs@6.0.0","symbols":["PNG.sync.read"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-pngjs-sync-read",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-pngjs-sync-read",
      "version": "1.0.0",
      "dependencies": {
        "pngjs": "6.0.0"
      }
    },
    "node_modules/pngjs": {
      "version": "6.0.0",
      "resolved": "https://registry.npmjs.org/pngjs/-/pngjs-6.0.0.tgz",
      "integrity": "sha512-TRzzuFRRmEoSW/p1KVAmiOgPco2Irlah+bGFCeNfJXxxYGwSw7YwAOAcd7X28K/m5bjBWKsC29KyoMfHbypayg==",
      "license": "MIT",
      "engines": {
        "node": ">=12.13.0"
      }
    }
  }
}

{
  "name": "sample-pngjs-sync-read",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "description": "Clean-room verification for PNG.sync.read in pkg:npm/pngjs@6.0.0",
  "dependencies": {
    "pngjs": "6.0.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify PNG.sync.read in pkg:npm/pngjs@6.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/pngjs@6.0.0"
  ],
  "symbols": [
    "PNG.sync.read"
  ]
}

import { PNG } from 'pngjs';

/**
 * Synchronously parses a PNG buffer into a PNG instance.
 *
 * @param {Buffer} buffer - Raw PNG file buffer.
 * @param {object} [options] - Parsing options passed to PNG.sync.read.
 * @returns {PNG} Decoded PNG instance containing width, height, data (RGBA buffer), etc.
 */
export function parsePng(buffer, options) {
  return PNG.sync.read(buffer, options);
}

/**
 * Synchronously creates a PNG buffer from raw RGBA pixel data.
 *
 * @param {number} width - Image width.
 * @param {number} height - Image height.
 * @param {Buffer|Uint8Array} [rgbaData] - Optional RGBA pixel buffer of length width * height * 4.
 * @returns {Buffer} Encoded PNG buffer.
 */
export function createPngBuffer(width, height, rgbaData) {
  const png = new PNG({ width, height });
  if (rgbaData) {
    Buffer.from(rgbaData).copy(png.data);
  }
  return PNG.sync.write(png);
}

export { PNG };

import assert from 'node:assert/strict';
import { Buffer } from 'node:buffer';
import { PNG, parsePng, createPngBuffer } from '../src/index.mjs';

// Contract 1: PNG.sync.read exists as a synchronous parsing function on PNG.sync
{
  assert.equal(typeof PNG.sync, 'object', 'PNG.sync must be an object');
  assert.equal(typeof PNG.sync.read, 'function', 'PNG.sync.read must be a function');
  assert.equal(typeof parsePng, 'function', 'parsePng wrapper must be a function');
}

// Contract 2: PNG.sync.read synchronously parses a valid PNG buffer and extracts dimensions and RGBA pixel buffer
{
  const width = 2;
  const height = 2;
  const rawRgba = Buffer.from([
    255,   0,   0, 255, // Pixel (0, 0): Red
      0, 255,   0, 255, // Pixel (1, 0): Green
      0,   0, 255, 255, // Pixel (0, 1): Blue
    255, 255,   0, 128, // Pixel (1, 1): Semi-transparent Yellow
  ]);

  const pngBuffer = createPngBuffer(width, height, rawRgba);
  assert.ok(Buffer.isBuffer(pngBuffer), 'createPngBuffer must return a Buffer');
  assert.ok(pngBuffer.length > 0, 'PNG buffer must not be empty');

  // Parse using PNG.sync.read directly
  const decoded = PNG.sync.read(pngBuffer);

  assert.equal(decoded.width, width, 'Decoded width must match original width');
  assert.equal(decoded.height, height, 'Decoded height must match original height');
  assert.ok(Buffer.isBuffer(decoded.data), 'Decoded data must be a Buffer');
  assert.equal(decoded.data.length, width * height * 4, 'Decoded data length must equal width * height * 4');

  // Verify pixel byte values
  assert.deepEqual(Array.from(decoded.data), Array.from(rawRgba), 'Decoded pixel data must match input RGBA bytes');
}

// Contract 3: PNG.sync.read accepts optional configuration options such as skipRescale
{
  const width = 1;
  const height = 1;
  const rawRgba = Buffer.from([120, 150, 200, 255]);
  const pngBuffer = createPngBuffer(width, height, rawRgba);

  const decodedWithOptions = PNG.sync.read(pngBuffer, { skipRescale: true });
  assert.equal(decodedWithOptions.width, 1);
  assert.equal(decodedWithOptions.height, 1);
  assert.deepEqual(Array.from(decodedWithOptions.data), [120, 150, 200, 255]);
}

// Contract 4: PNG.sync.read throws an error when provided with an invalid or corrupted PNG buffer
{
  const invalidBuffer = Buffer.from('invalid non-png data payload');
  assert.throws(
    () => {
      PNG.sync.read(invalidBuffer);
    },
    /unrecognised|unrecognized|signature|invalid|corrupted|chunk|stream/i,
    'PNG.sync.read must throw when buffer does not have valid PNG data'
  );

  const truncatedBuffer = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]); // Header only, missing chunks
  assert.throws(
    () => {
      PNG.sync.read(truncatedBuffer);
    },
    /error|invalid|truncated|eof|stream|end|chunk|unrecognised|unrecognized/i,
    'PNG.sync.read must throw on truncated PNG buffer'
  );
}

console.log('Contract passed: PNG.sync.read behavior in pkg:npm/pngjs@6.0.0 successfully verified.');