@litfamily/litopencode 1.0.0

package/skills/visual-qa/scripts/evidence.mjs

@@ -0,0 +1,271 @@
+const hashPattern = /^sha256:[a-f0-9]{64}$/u;
+const tierConditions = Object.freeze({
+  smoke: Object.freeze(["app-started", "primary-route", "critical-state"]),
+  full: Object.freeze([
+    "finite-inventory-complete",
+    "mechanical-checks-complete",
+    "accessibility-checks-complete"
+  ]),
+  "reference-fidelity": Object.freeze([
+    "finite-inventory-complete",
+    "reference-hash-match",
+    "paired-captures-comparable",
+    "reference-findings-complete"
+  ])
+});
+export const tierInventory = Object.freeze({
+  smoke: Object.freeze(["route", "interaction", "viewport-min", "viewport-max"]),
+  full: Object.freeze([
+    "route",
+    "screen",
+    "state",
+    "viewport",
+    "theme",
+    "permission",
+    "auth",
+    "error",
+    "loading",
+    "empty",
+    "tui-size"
+  ]),
+  "reference-fidelity": Object.freeze([
+    "route",
+    "screen",
+    "state",
+    "viewport",
+    "theme",
+    "permission",
+    "auth",
+    "error",
+    "loading",
+    "empty",
+    "tui-size",
+    "reference-comparison"
+  ])
+});
+export const capabilityCodes = Object.freeze({
+  capture: "BLOCKED_RENDERER_UNAVAILABLE",
+  auth: "BLOCKED_AUTH_UNAVAILABLE",
+  test_account_safe: "BLOCKED_TEST_ACCOUNT_UNSAFE",
+  independent_review: "BLOCKED_INDEPENDENT_REVIEW_UNAVAILABLE"
+});
+const rootKeys = ["schema_id", "design_contract_hash", "source_revision", "tier", "created_at", "maximum_age_seconds", "freshness", "capabilities", "captures", "inventory", "mechanical_checks", "accessibility_checks", "tui_checks", "review_receipt_hashes", "findings", "exception_references", "cleanup", "verdict"];
+const captureKeys = ["capture_id", "source_hash", "capture_hash", "created_at", "viewport", "dpr", "os", "runtime", "runtime_version", "font_set", "locale", "reduced_motion", "animation_settling", "color_scheme", "auth_owner", "process_owner"];
+const betaCaptureKeys = [...captureKeys, "path", "byte_length", "width", "height"];
+const checkKeys = ["id", "status", "evidence_path", "evidence_hash"];
+const betaCheckKeys = [...checkKeys, "channel"];
+export const evidenceChannels = Object.freeze([
+  "tests",
+  "browser",
+  "keyboard",
+  "accessibility-tree",
+  "screen-reader",
+  "performance",
+  "localization"
+]);
+const maximumTextCharacters = 4096;
+const drivePrefix = /^[A-Za-z]:/u;
+const pathControlCharacter = /[\u0000-\u001f\u007f]/u;
+function object(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+const exact = (value, keys) => object(value) && Object.keys(value).every((key) => keys.includes(key));
+function isEvidenceText(value) {
+  return typeof value === "string" && value.length > 0 && [...value].length <= maximumTextCharacters;
+}
+export function isSchemaRelativeCapturePath(value) {
+  if (
+    !isEvidenceText(value) ||
+    value.startsWith("/") ||
+    value.includes("/") ||
+    value.includes("\\") ||
+    drivePrefix.test(value) ||
+    pathControlCharacter.test(value)
+  ) return false;
+  return value.split("/").every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+}
+function parseTime(value) {
+  const time = Date.parse(value);
+  return Number.isFinite(time) ? time : undefined;
+}
+function matchingHashes(input) {
+  return (
+    typeof input.expectedSourceHash === "string" &&
+    input.expectedSourceHash === input.actualSourceHash &&
+    typeof input.expectedCaptureHash === "string" &&
+    input.expectedCaptureHash === input.actualCaptureHash
+  );
+}
+function checkEvidenceItem(item, statuses, betaPath = false, requireChannel = false) {
+  return (
+    object(item) &&
+    isEvidenceText(item.id) &&
+    statuses.includes(item.status) &&
+    (betaPath ? isSchemaRelativeCapturePath(item.evidence_path) : isEvidenceText(item.evidence_path)) &&
+    (!requireChannel || evidenceChannels.includes(item.channel)) &&
+    hashPattern.test(item.evidence_hash)
+  );
+}
+export function validateEvidenceManifest(manifest) {
+  const errors = [];
+  if (!object(manifest)) return { valid: false, errors: ["manifest must be an object"] };
+  if (!exact(manifest, rootKeys)) errors.push("manifest contains unknown fields");
+  const beta = manifest.schema_id === "litfamily.evidence-manifest/v1beta1";
+  if (!beta && manifest.schema_id !== "litfamily.evidence-manifest/v1alpha1") {
+    errors.push("schema_id must be exact v1alpha1 or v1beta1");
+  }
+  if (!hashPattern.test(manifest.design_contract_hash)) errors.push("design_contract_hash is invalid");
+  if (!isEvidenceText(manifest.source_revision)) {
+    errors.push("source_revision must be non-empty text");
+  }
+  if (!tierInventory[manifest.tier]) errors.push("tier is invalid");
+  if (parseTime(manifest.created_at) === undefined) errors.push("created_at is invalid");
+  if (
+    !Number.isFinite(manifest.maximum_age_seconds) ||
+    manifest.maximum_age_seconds <= 0 ||
+    manifest.maximum_age_seconds > 86400
+  ) {
+    errors.push("maximum_age_seconds must be finite and between 1 and 86400");
+  }
+  if (!exact(manifest.freshness, ["assessed_at", "expires_at", "fresh", "contract_hash_match", "source_hash_match", "capture_hash_match"])) errors.push("freshness is required or contains unknown fields");
+  else {
+    for (const key of ["fresh", "contract_hash_match", "source_hash_match", "capture_hash_match"]) {
+      if (typeof manifest.freshness[key] !== "boolean") errors.push(`freshness.${key} must be boolean`);
+    }
+    if (parseTime(manifest.freshness.assessed_at) === undefined || parseTime(manifest.freshness.expires_at) === undefined) {
+      errors.push("freshness timestamps are invalid");
+    }
+  }
+  if (!exact(manifest.capabilities, Object.keys(capabilityCodes))) errors.push("capabilities are required or contain unknown fields");
+  else {
+    for (const key of Object.keys(capabilityCodes)) {
+      if (typeof manifest.capabilities[key] !== "boolean") errors.push(`capabilities.${key} must be boolean`);
+    }
+  }
+  if (!Array.isArray(manifest.captures) || manifest.captures.length === 0 || manifest.captures.length > 10000) {
+    errors.push("captures must be finite and non-empty");
+  } else {
+    for (const capture of manifest.captures) {
+      if (
+        !exact(capture, beta ? betaCaptureKeys : captureKeys) ||
+        !hashPattern.test(capture.source_hash) ||
+        !hashPattern.test(capture.capture_hash) ||
+        parseTime(capture.created_at) === undefined ||
+        !Number.isFinite(capture.dpr) ||
+        capture.dpr <= 0 ||
+        capture.dpr > 8 ||
+        !Array.isArray(capture.font_set) ||
+        capture.font_set.length === 0 ||
+        capture.font_set.some((font) => !isEvidenceText(font)) ||
+        typeof capture.reduced_motion !== "boolean" ||
+        ["capture_id", "viewport", "os", "runtime", "runtime_version", "locale", "animation_settling",
+          "color_scheme", "auth_owner", "process_owner"].some(
+          (field) => !isEvidenceText(capture[field])
+        )
+      ) errors.push("capture metadata is incomplete");
+      if (beta && (
+        !isSchemaRelativeCapturePath(capture.path) ||
+        !Number.isInteger(capture.byte_length) || capture.byte_length < 1 || capture.byte_length > 25 * 1024 * 1024 ||
+        !Number.isInteger(capture.width) || capture.width < 1 || capture.width > 16384 ||
+        !Number.isInteger(capture.height) || capture.height < 1 || capture.height > 16384
+      )) errors.push("beta material capture metadata is invalid");
+    }
+  }
+  if (!Array.isArray(manifest.inventory) || manifest.inventory.length === 0 || manifest.inventory.length > 10000) {
+    errors.push("inventory must be finite and non-empty");
+  } else {
+    for (const item of manifest.inventory) {
+      if (
+        !exact(item, ["id", "kind", "status", "exception_id", "evidence_path", "evidence_hash"]) ||
+        !checkEvidenceItem(item, ["captured", "not_applicable", "accepted_exception", "blocked"], beta) ||
+        !isEvidenceText(item.kind) ||
+        (item.status === "accepted_exception"
+          ? !isEvidenceText(item.exception_id)
+          : item.exception_id !== null)
+      ) errors.push("inventory item is invalid");
+    }
+    if (new Set(manifest.inventory.map((item) => item.id)).size !== manifest.inventory.length) {
+      errors.push("inventory ids must be unique");
+    }
+  }
+  for (const field of ["mechanical_checks", "accessibility_checks", "tui_checks"]) {
+    const checks = manifest[field];
+    if (
+      !Array.isArray(checks) ||
+      checks.length === 0 ||
+      checks.length > 10000 ||
+      checks.some(
+        (item) =>
+          !exact(item, beta ? betaCheckKeys : checkKeys) ||
+          !checkEvidenceItem(item, ["pass", "fail", "blocked", "not_applicable"], beta, beta)
+      )
+    ) errors.push(`${field} must contain finite evidence-backed checks`);
+  }
+  const expectedReviewReceipts = beta && manifest.tier === "smoke" ? 0 : 2;
+  if (
+    !Array.isArray(manifest.review_receipt_hashes) ||
+    manifest.review_receipt_hashes.length !== expectedReviewReceipts ||
+    new Set(manifest.review_receipt_hashes).size !== expectedReviewReceipts ||
+    manifest.review_receipt_hashes.some((hash) => !hashPattern.test(hash))
+  ) errors.push(beta && manifest.tier === "smoke"
+    ? "smoke evidence without review inventory requires zero review receipt hashes"
+    : "full and reference-fidelity evidence require exactly two distinct review receipt hashes");
+  if (
+    !Array.isArray(manifest.findings) ||
+    manifest.findings.some(
+      (finding) =>
+        !exact(finding, ["code", "severity", "evidence"]) ||
+        !isEvidenceText(finding.code) ||
+        !["critical", "high", "medium", "low", "info"].includes(finding.severity) ||
+        !Array.isArray(finding.evidence) ||
+        finding.evidence.length === 0 ||
+        finding.evidence.some((hash) => !hashPattern.test(hash))
+    ) ||
+    !Array.isArray(manifest.exception_references) ||
+    manifest.exception_references.some((id) => !isEvidenceText(id)) ||
+    new Set(manifest.exception_references).size !== manifest.exception_references.length
+  ) {
+    errors.push("findings and exception_references must be arrays");
+  }
+  if (
+    !exact(manifest.cleanup, ["owned_processes_stopped", "temporary_artifacts_removed", "remaining"]) ||
+    typeof manifest.cleanup.owned_processes_stopped !== "boolean" ||
+    typeof manifest.cleanup.temporary_artifacts_removed !== "boolean" ||
+    !Array.isArray(manifest.cleanup.remaining) ||
+    manifest.cleanup.remaining.length > 1000 ||
+    manifest.cleanup.remaining.some((item) => !isEvidenceText(item))
+  ) errors.push("cleanup receipt is incomplete");
+  if (!["PASS", "REVISE", "FAIL", "BLOCKED"].includes(manifest.verdict)) errors.push("verdict is invalid");
+  return { valid: errors.length === 0, errors };
+}
+export function evaluateEvidenceFreshness(input = {}) {
+  if (!matchingHashes(input)) {
+    return { accepted: false, fresh: false, code: "BLOCKED_SCHEMA_OR_PAYLOAD_MISMATCH", verdict: "BLOCKED" };
+  }
+  if (!Number.isFinite(input.maximumAgeSeconds) || input.maximumAgeSeconds < 0) {
+    throw new Error("maximumAgeSeconds must be a non-negative finite number");
+  }
+  const age = parseTime(input.now) - parseTime(input.createdAt);
+  // A capture dated after the moment it is being assessed is a broken clock or a
+  // forged timestamp, not old evidence, so it gets its own code instead of being
+  // reported as stale.
+  if (Number.isFinite(age) && age < 0) {
+    return { accepted: false, fresh: false, code: "BLOCKED_EVIDENCE_FUTURE", verdict: "BLOCKED" };
+  }
+  if (!Number.isFinite(age) || age > input.maximumAgeSeconds * 1000) {
+    return { accepted: false, fresh: false, code: "BLOCKED_EVIDENCE_STALE", verdict: "BLOCKED" };
+  }
+  return { accepted: true, fresh: true, verdict: "READY" };
+}
+export function completionConditionsForTier(tier) {
+  if (!tierConditions[tier]) throw new Error(`Unknown visual-QA tier: ${String(tier)}`);
+  return [...tierConditions[tier]];
+}
+export function evaluateTierCompletion({ tier, completed } = {}) {
+  if (!Array.isArray(completed)) throw new Error("completed must be an array");
+  const conditions = completionConditionsForTier(tier);
+  const unknown = completed.filter((condition) => !conditions.includes(condition));
+  if (unknown.length > 0) throw new Error(`Unknown ${tier} completion condition: ${unknown[0]}`);
+  const missing = conditions.filter((condition) => !new Set(completed).has(condition));
+  return { complete: missing.length === 0, missing, tier, verdict: missing.length === 0 ? "READY" : "REVISE" };
+}

package/skills/visual-qa/scripts/png-decode.mjs

@@ -0,0 +1,146 @@
+import { decodePngStructure } from "./png.mjs";
+
+const channels = Object.freeze({ 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 });
+
+function paeth(a, b, c) {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+}
+
+function unfilter(parsed) {
+  const rows = [];
+  const bpp = Math.max(1, Math.ceil((channels[parsed.colorType] * parsed.bitDepth) / 8));
+  let offset = 0;
+  let previous = Buffer.alloc(parsed.rowBytes);
+  for (let y = 0; y < parsed.height; y += 1) {
+    const filter = parsed.scanlines[offset];
+    const raw = parsed.scanlines.subarray(offset + 1, offset + 1 + parsed.rowBytes);
+    const row = Buffer.alloc(parsed.rowBytes);
+    if (filter > 4) throw new Error(`PNG filter ${filter} is invalid`);
+    for (let x = 0; x < raw.length; x += 1) {
+      const left = x >= bpp ? row[x - bpp] : 0;
+      const up = previous[x] ?? 0;
+      const upperLeft = x >= bpp ? previous[x - bpp] : 0;
+      const predictor =
+        filter === 0 ? 0 :
+        filter === 1 ? left :
+        filter === 2 ? up :
+        filter === 3 ? Math.floor((left + up) / 2) :
+        paeth(left, up, upperLeft);
+      row[x] = (raw[x] + predictor) & 0xff;
+    }
+    rows.push(row);
+    previous = row;
+    offset += parsed.rowBytes + 1;
+  }
+  return rows;
+}
+
+function rawSample(row, index, depth) {
+  if (depth === 16) return row.readUInt16BE(index * 2);
+  if (depth === 8) return row[index];
+  const perByte = 8 / depth;
+  const shift = 8 - depth * ((index % perByte) + 1);
+  return (row[Math.floor(index / perByte)] >>> shift) & ((1 << depth) - 1);
+}
+
+function normalizedSample(row, index, depth) {
+  const raw = rawSample(row, index, depth);
+  return depth === 16 ? raw >>> 8 : Math.round((raw * 255) / ((1 << depth) - 1));
+}
+
+function transparencyKey(buffer, offset = 0) {
+  return buffer?.length >= offset + 2 ? buffer.readUInt16BE(offset) : undefined;
+}
+
+export function decodePng(input) {
+  const parsed = decodePngStructure(input);
+  if (!parsed.ok) return parsed;
+  let rows;
+  try {
+    rows = unfilter(parsed);
+  } catch (error) {
+    return { code: "PNG_DECODE_INVALID", detail: error instanceof Error ? error.message : String(error), ok: false };
+  }
+  const rgba = Buffer.alloc(parsed.width * parsed.height * 4);
+  const count = channels[parsed.colorType];
+  for (let y = 0; y < parsed.height; y += 1) {
+    const row = rows[y];
+    for (let x = 0; x < parsed.width; x += 1) {
+      const sample = x * count;
+      const output = (y * parsed.width + x) * 4;
+      let red;
+      let green;
+      let blue;
+      let alpha = 255;
+      if (parsed.colorType === 0) {
+        const raw = rawSample(row, sample, parsed.bitDepth);
+        red = normalizedSample(row, sample, parsed.bitDepth);
+        green = red;
+        blue = red;
+        if (raw === transparencyKey(parsed.transparency)) alpha = 0;
+      } else if (parsed.colorType === 2) {
+        const rawRed = rawSample(row, sample, parsed.bitDepth);
+        const rawGreen = rawSample(row, sample + 1, parsed.bitDepth);
+        const rawBlue = rawSample(row, sample + 2, parsed.bitDepth);
+        red = normalizedSample(row, sample, parsed.bitDepth);
+        green = normalizedSample(row, sample + 1, parsed.bitDepth);
+        blue = normalizedSample(row, sample + 2, parsed.bitDepth);
+        if (
+          rawRed === transparencyKey(parsed.transparency) &&
+          rawGreen === transparencyKey(parsed.transparency, 2) &&
+          rawBlue === transparencyKey(parsed.transparency, 4)
+        ) alpha = 0;
+      } else if (parsed.colorType === 3) {
+        const index = rawSample(row, sample, parsed.bitDepth);
+        const paletteOffset = index * 3;
+        if (paletteOffset + 2 >= parsed.palette.length) {
+          return { code: "PNG_PALETTE_INVALID", detail: `Palette index ${index} is absent`, ok: false };
+        }
+        red = parsed.palette[paletteOffset];
+        green = parsed.palette[paletteOffset + 1];
+        blue = parsed.palette[paletteOffset + 2];
+        alpha = parsed.transparency?.[index] ?? 255;
+      } else if (parsed.colorType === 4) {
+        red = normalizedSample(row, sample, parsed.bitDepth);
+        green = red;
+        blue = red;
+        alpha = normalizedSample(row, sample + 1, parsed.bitDepth);
+      } else {
+        red = normalizedSample(row, sample, parsed.bitDepth);
+        green = normalizedSample(row, sample + 1, parsed.bitDepth);
+        blue = normalizedSample(row, sample + 2, parsed.bitDepth);
+        alpha = normalizedSample(row, sample + 3, parsed.bitDepth);
+      }
+      rgba.set([red, green, blue, alpha], output);
+    }
+  }
+  return { height: parsed.height, ok: true, rgba, width: parsed.width };
+}
+
+export function comparePngs(expectedInput, actualInput) {
+  const expected = decodePng(expectedInput);
+  if (!expected.ok) return expected;
+  const actual = decodePng(actualInput);
+  if (!actual.ok) return actual;
+  if (expected.width !== actual.width || expected.height !== actual.height) {
+    return { code: "PNG_DIMENSION_MISMATCH", ok: false };
+  }
+  let difference = 0;
+  let alphaDamagedPixels = 0;
+  for (let index = 0; index < expected.rgba.length; index += 4) {
+    for (let channel = 0; channel < 4; channel += 1) {
+      difference += Math.abs(expected.rgba[index + channel] - actual.rgba[index + channel]);
+    }
+    if (expected.rgba[index + 3] !== actual.rgba[index + 3]) alphaDamagedPixels += 1;
+  }
+  return {
+    alphaDamagedPixels,
+    comparedPixels: expected.width * expected.height,
+    ok: true,
+    similarity: 1 - difference / (expected.rgba.length * 255)
+  };
+}

package/skills/visual-qa/scripts/png.mjs

@@ -0,0 +1,154 @@
+import { inflateSync } from "node:zlib";
+
+const signature = Buffer.from("89504e470d0a1a0a", "hex");
+const maximumFileBytes = 25 * 1024 * 1024;
+const maximumAxis = 16_384;
+const maximumPixels = 64_000_000;
+const maximumDecodedBytes = 256 * 1024 * 1024;
+const allowedDepths = Object.freeze({
+  0: [1, 2, 4, 8, 16],
+  2: [8, 16],
+  3: [1, 2, 4, 8],
+  4: [8, 16],
+  6: [8, 16]
+});
+const channels = Object.freeze({ 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 });
+
+function crc32(buffer) {
+  let crc = 0xffffffff;
+  for (const byte of buffer) {
+    crc ^= byte;
+    for (let bit = 0; bit < 8; bit += 1) crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function rejected(code, detail) {
+  return { code, detail, ok: false };
+}
+
+function dimensionFailure(width, height, bitDepth = 8, colorType = 6) {
+  if (width < 1 || height < 1 || width > maximumAxis || height > maximumAxis) {
+    return rejected("PNG_DIMENSION_LIMIT", `PNG dimensions ${width}x${height} exceed the positive ${maximumAxis}-pixel axis limit`);
+  }
+  if (width * height > maximumPixels) return rejected("PNG_RESOURCE_LIMIT", "PNG exceeds 64 megapixels");
+  const channelCount = channels[colorType] ?? 4;
+  const decodedBytes = Math.ceil((width * height * channelCount * bitDepth) / 8);
+  if (decodedBytes > maximumDecodedBytes) return rejected("PNG_RESOURCE_LIMIT", "PNG decoded storage exceeds 256 MiB");
+  return undefined;
+}
+
+function preflightDimensions(input) {
+  if (input.length < 24 || input.readUInt32BE(8) !== 13 || input.toString("ascii", 12, 16) !== "IHDR") return undefined;
+  return dimensionFailure(input.readUInt32BE(16), input.readUInt32BE(20));
+}
+
+function parseIhdr(data) {
+  if (data.length !== 13) return { failure: rejected("PNG_IHDR_INVALID", "IHDR length must be 13") };
+  const width = data.readUInt32BE(0);
+  const height = data.readUInt32BE(4);
+  const bitDepth = data[8];
+  const colorType = data[9];
+  if (!(colorType in allowedDepths) || !allowedDepths[colorType].includes(bitDepth)) {
+    return { failure: rejected("PNG_COLOR_DEPTH_INVALID", `Unsupported color type ${colorType} and bit depth ${bitDepth}`) };
+  }
+  if (data[10] !== 0 || data[11] !== 0 || data[12] !== 0) {
+    return { failure: rejected("PNG_IHDR_INVALID", "Unsupported compression, filter, or interlace method") };
+  }
+  return { bitDepth, colorType, height, width, failure: dimensionFailure(width, height, bitDepth, colorType) };
+}
+
+export function decodePngStructure(input) {
+  if (!Buffer.isBuffer(input)) throw new TypeError("PNG input must be a Buffer");
+  if (input.length > maximumFileBytes) return rejected("PNG_FILE_LIMIT", "PNG exceeds 25 MiB");
+  if (input.length < signature.length || !input.subarray(0, signature.length).equals(signature)) {
+    return rejected("PNG_SIGNATURE_INVALID", "PNG signature is missing or invalid");
+  }
+  const preflight = preflightDimensions(input);
+  if (preflight !== undefined) return preflight;
+
+  let offset = signature.length;
+  let ihdr;
+  let sawIdat = false;
+  let endedIdat = false;
+  let sawIend = false;
+  const compressed = [];
+  let palette;
+  let transparency;
+  while (offset < input.length) {
+    if (input.length - offset < 12) return rejected("PNG_TRUNCATED", "PNG chunk framing is truncated");
+    const length = input.readUInt32BE(offset);
+    const end = offset + 12 + length;
+    if (end > input.length) return rejected("PNG_TRUNCATED", "PNG chunk payload or CRC is truncated");
+    const type = input.toString("ascii", offset + 4, offset + 8);
+    const data = input.subarray(offset + 8, offset + 8 + length);
+    const expectedCrc = input.readUInt32BE(offset + 8 + length);
+    const actualCrc = crc32(input.subarray(offset + 4, offset + 8 + length));
+    if (actualCrc !== expectedCrc) return rejected("PNG_CRC_INVALID", `PNG ${type} CRC mismatch`);
+    if (offset === signature.length && type !== "IHDR") return rejected("PNG_CHUNK_ORDER_INVALID", "IHDR must be first");
+    if (type === "IHDR") {
+      if (ihdr !== undefined) return rejected("PNG_CHUNK_ORDER_INVALID", "IHDR must occur once");
+      ihdr = parseIhdr(data);
+      if (ihdr.failure !== undefined) return ihdr.failure;
+    } else if (type === "IDAT") {
+      if (ihdr === undefined || endedIdat) return rejected("PNG_CHUNK_ORDER_INVALID", "IDAT order is invalid");
+      sawIdat = true;
+      compressed.push(data);
+    } else if (type === "IEND") {
+      if (length !== 0 || !sawIdat) return rejected("PNG_CHUNK_ORDER_INVALID", "IEND must follow image data and be empty");
+      sawIend = true;
+      offset = end;
+      break;
+    } else if (type === "PLTE") {
+      if (sawIdat || data.length === 0 || data.length % 3 !== 0 || data.length > 768) {
+        return rejected("PNG_PALETTE_INVALID", "PLTE must precede IDAT and contain 1 to 256 RGB entries");
+      }
+      palette = Buffer.from(data);
+    } else if (type === "tRNS") {
+      if (sawIdat) return rejected("PNG_CHUNK_ORDER_INVALID", "tRNS must precede IDAT");
+      transparency = Buffer.from(data);
+    } else {
+      if (sawIdat) endedIdat = true;
+      if (/^[A-Z]/u.test(type)) return rejected("PNG_CRITICAL_CHUNK_UNSUPPORTED", `Unsupported critical chunk ${type}`);
+    }
+    offset = end;
+  }
+  if (!sawIend) return rejected("PNG_TRUNCATED", "PNG is missing IEND");
+  if (offset !== input.length) return rejected("PNG_TRAILING_DATA", "PNG contains data after IEND");
+
+  const rowBytes = Math.ceil((ihdr.width * channels[ihdr.colorType] * ihdr.bitDepth) / 8);
+  const expectedDecoded = (rowBytes + 1) * ihdr.height;
+  if (expectedDecoded > maximumDecodedBytes) return rejected("PNG_RESOURCE_LIMIT", "PNG decoded scanlines exceed 256 MiB");
+  try {
+    const decoded = inflateSync(Buffer.concat(compressed), { maxOutputLength: maximumDecodedBytes });
+    if (decoded.length !== expectedDecoded) return rejected("PNG_DECODE_INVALID", "PNG decoded scanline length is invalid");
+    if (ihdr.colorType === 3 && palette === undefined) return rejected("PNG_PALETTE_INVALID", "Indexed PNG requires PLTE");
+    return {
+      bitDepth: ihdr.bitDepth,
+      colorType: ihdr.colorType,
+      decodedBytes: decoded.length,
+      height: ihdr.height,
+      ok: true,
+      palette,
+      rowBytes,
+      scanlines: decoded,
+      transparency,
+      width: ihdr.width
+    };
+  } catch (error) {
+    return rejected("PNG_DECODE_INVALID", error instanceof Error ? error.message : String(error));
+  }
+}
+
+export function inspectPng(input) {
+  const parsed = decodePngStructure(input);
+  if (!parsed.ok) return parsed;
+  return {
+    bitDepth: parsed.bitDepth,
+    colorType: parsed.colorType,
+    decodedBytes: parsed.decodedBytes,
+    height: parsed.height,
+    ok: true,
+    width: parsed.width
+  };
+}