@utilix-tech/sdk 0.94.0 → 0.95.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Full release notes for all Utilix surfaces (browser tools, REST API, SDKs, MCP server) live at [utilix.tech/changelog](https://utilix.tech/changelog). This file tracks just this package.
 
+## 0.95.0
+- Add `readPngChunks` (png-chunk-inspector): walk a PNG's chunk stream directly from its bytes to report every chunk's type, offset, size, and CRC-32 validity, plus the decoded IHDR header and common ancillary chunks (tEXt, pHYs, gAMA, tIME, acTL).
+- Add `estimateAudioFileSize` (audio-file-size-estimator): estimate an audio file's size before recording or exporting it, uncompressed PCM size from sample rate/bit depth/channels or compressed size from a target bitrate.
+
 ## 0.94.0
 - Add `buildAltSvcHeader`/`parseAltSvcHeader` (alt-svc-header-builder): build an `Alt-Svc` response header (RFC 7838) from one or more alternative services with a plain-English note per protocol-id, flagging outdated HTTP/3 draft protocol-ids, or parse an existing header back into its alternatives, including the special `clear` value.
 

package/README.md

@@ -1,6 +1,6 @@
 # @utilix-tech/sdk
 
-**740 developer utility functions for Node.js: runs locally, no API key required.**
+**742 developer utility functions for Node.js: runs locally, no API key required.**
 
 [![npm version](https://img.shields.io/npm/v/@utilix-tech/sdk?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@utilix-tech/sdk)
 [![npm downloads](https://img.shields.io/npm/dm/@utilix-tech/sdk?style=flat-square)](https://www.npmjs.com/package/@utilix-tech/sdk)
@@ -772,6 +772,16 @@ summarizeGitDiffStat(" src/foo.ts | 12 +++++-------\n 1 file changed, 5 insertio
 import { buildAltSvcHeader, parseAltSvcHeader } from "@utilix-tech/sdk/network";
 buildAltSvcHeader([{ protocolId: "h3", port: 443, maxAge: 86400 }]);
 // { header: 'Alt-Svc: h3=":443"; ma=86400', headerValue: 'h3=":443"; ma=86400', entries: [{ protocolId: "h3", authority: ":443", maxAge: 86400, persist: false, note: "..." }], cleared: false, warnings: [] }
+
+// Walk a PNG's chunk stream directly from its bytes: type, offset, size, CRC validity
+import { readPngChunks } from "@utilix-tech/sdk/media";
+readPngChunks(pngBytes);
+// { valid: true, fileSize: 1024, chunkCount: 5, chunks: [{ type: "IHDR", offset: 8, dataLength: 13, crcValid: true, critical: true }, ...], header: { width: 64, height: 64, bitDepth: 8, colorType: "rgba", hasAlpha: true, interlace: false }, textChunks: [], physicalDimensions: null, gamma: null, lastModified: null, isAnimated: false }
+
+// Estimate an audio file's size before recording/exporting it
+import { estimateAudioFileSize } from "@utilix-tech/sdk/units";
+estimateAudioFileSize({ mode: "pcm", durationSeconds: 60, sampleRateHz: 44100, bitDepth: 16, channels: 2 });
+// { mode: "pcm", durationSeconds: 60, sampleRateHz: 44100, bitDepth: 16, channels: 2, dataBytes: 10584000, fileSizeBytes: 10584044, fileSizeMB: 10.58, fileSizeMiB: 10.09 }
 ```
 
 ---
@@ -1090,7 +1100,7 @@ readMidiInfo(new Uint8Array(midiBytes));
 | `@utilix-tech/sdk/data` | CSV, YAML, TOML, XML, INI, NDJSON parse and convert, NDJSON record deduplicator, SRT/WebVTT subtitles, Markdown front matter parser, YAML anchor/alias resolver, CSV column type inferencer, Markdown table column aligner, Markdown heading hierarchy validator, Markdown internal link checker |
 | `@utilix-tech/sdk/generators` | UUID v4/v7, ULID, passwords, strength check, entropy estimator, fake data, CSP nonce generator |
 | `@utilix-tech/sdk/time` | Date diff, timezone convert, cron parse, relative time |
-| `@utilix-tech/sdk/units` | Bytes, CSS px/rem, number bases, currency format, credit card/IBAN/barcode/ISBN/VIN/ISIN validation, loan calculator, EMI calculator, compound/simple interest calculators, VAT/sales tax calculator, tip/bill split calculator, break-even point calculator, Rule of 72 calculator, savings goal calculator, ROI calculator, cash denomination/till calculator, payback period calculator, CD maturity calculator, debt-to-income ratio calculator, freelancer hourly rate calculator, debt snowball/avalanche payoff planner, tax-equivalent yield calculator, mortgage discount points break-even calculator, loan prepayment penalty calculator, data transfer time / required bandwidth estimator, real rate of return (Fisher equation) calculator, sales commission calculator (flat or tiered), annuity payout calculator, semver range intersection checker |
+| `@utilix-tech/sdk/units` | Bytes, CSS px/rem, number bases, currency format, credit card/IBAN/barcode/ISBN/VIN/ISIN validation, loan calculator, EMI calculator, compound/simple interest calculators, VAT/sales tax calculator, tip/bill split calculator, break-even point calculator, Rule of 72 calculator, savings goal calculator, ROI calculator, cash denomination/till calculator, payback period calculator, CD maturity calculator, debt-to-income ratio calculator, freelancer hourly rate calculator, debt snowball/avalanche payoff planner, tax-equivalent yield calculator, mortgage discount points break-even calculator, loan prepayment penalty calculator, data transfer time / required bandwidth estimator, real rate of return (Fisher equation) calculator, sales commission calculator (flat or tiered), annuity payout calculator, semver range intersection checker, audio file size estimator |
 | `@utilix-tech/sdk/network` | HTTP status codes, IP validation, country flags, geolocation URLs, HAR file parsing, User-Agent parsing, IPv6 address compress/expand, Permissions-Policy header builder, Client Hints header builder/parser, Content-Disposition header builder/parser, X-Content-Type-Options header builder/risk assessor, sitemap.xml validator, sitemap index splitter, robots.txt validator, robots.txt generator, Prefer header builder/parser (RFC 7240), Retry-After header builder/parser (RFC 9110), Priority header builder/parser (RFC 9218), WebSocket close code reference/lookup, Strict-Transport-Security (HSTS) header builder/parser, X-Robots-Tag header builder/parser, WebSocket frame opcode reference/lookup, robots meta tag builder/parser, Cookie header byte-size budget calculator, Alt-Svc header builder/parser (RFC 7838) |
 | `@utilix-tech/sdk/api` | cURL build/parse, JWT decode/sign, JWKS parse, CORS headers, CSP header, TOTP/HOTP code generator, webhook HMAC signature verifier |
 | `@utilix-tech/sdk/code` | SQL format/minify, HTML format/minify, regex tester, GraphQL format, MIME type lookup, GitHub URL parsing, regex ReDoS detector, Conventional Commits linter, package.json exports field validator, package.json dependency range auditor, regex capture group/backreference visualizer, SVG sprite symbol extractor, ARIA role & attribute validator, database connection string parser, Markdown code fence language tag validator, SQL query parameter placeholder counter, Markdown link reference extractor, regex character class builder, Dockerfile linter, Mermaid diagram syntax validator |
@@ -1098,7 +1108,7 @@ readMidiInfo(new Uint8Array(midiBytes));
 | `@utilix-tech/sdk/css` | CSS gradient, box-shadow, border-radius, keyframe animation generators |
 | `@utilix-tech/sdk/misc` | SVG optimize/sanitize, file size format, Unicode inspector |
 | `@utilix-tech/sdk/ai_agent` | Token estimate/trim, chunk text, extract URLs/JSON/keywords, sanitize HTML, flatten/merge JSON, dedupe lines, validate schema, PII/secret/injection detect, vector similarity, few-shot prompt formatter, tool-definition schema linter, retry/backoff schedule calculator, prompt template variable extractor |
-| `@utilix-tech/sdk/media` | Image format & dimension reading from raw bytes (PNG, JPEG, GIF, WebP, BMP); PDF metadata reading; PDF page dimension/orientation listing; WAV audio info; ID3 tags; ICO favicon inspection; FLAC metadata reading; MP4/WebM video info; GIF frame/loop inspection |
+| `@utilix-tech/sdk/media` | Image format & dimension reading from raw bytes (PNG, JPEG, GIF, WebP, BMP); PDF metadata reading; PDF page dimension/orientation listing; WAV audio info; ID3 tags; ICO favicon inspection; FLAC metadata reading; MP4/WebM video info; GIF frame/loop inspection; PNG chunk stream inspection with CRC validation |
 
 ---
 

package/dist/{chunk-XAPHAUPI.js → chunk-G5NUC5MV.js}

@@ -70,6 +70,7 @@ __export(units_exports, {
   decimalToIpCidr: () => decimalToIpCidr,
   describePermissions: () => describePermissions,
   detectNegativeAmortization: () => detectNegativeAmortization,
+  estimateAudioFileSize: () => estimateAudioFileSize,
   fitIntoBox: () => fitIntoBox,
   formatNumber: () => formatNumber,
   formatValue: () => formatValue,
@@ -3166,5 +3167,55 @@ function detectNegativeAmortization(input) {
     capCrossedMonth
   };
 }
+var AUDIO_FILE_SIZE_WAV_HEADER_BYTES = 44;
+function estimateAudioFileSize(input) {
+  const { mode, durationSeconds } = input;
+  if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) {
+    return { error: "durationSeconds must be a positive number" };
+  }
+  const round22 = (n) => Math.round(n * 100) / 100;
+  if (mode === "pcm") {
+    const { sampleRateHz, bitDepth, channels } = input;
+    if (!Number.isFinite(sampleRateHz) || sampleRateHz <= 0) {
+      return { error: 'sampleRateHz must be a positive number for mode "pcm"' };
+    }
+    if (!Number.isFinite(bitDepth) || bitDepth <= 0) {
+      return { error: 'bitDepth must be a positive number for mode "pcm"' };
+    }
+    if (!Number.isInteger(channels) || channels <= 0) {
+      return { error: 'channels must be a positive whole number for mode "pcm"' };
+    }
+    const dataBytes = sampleRateHz * (bitDepth / 8) * channels * durationSeconds;
+    const fileSizeBytes = dataBytes + AUDIO_FILE_SIZE_WAV_HEADER_BYTES;
+    return {
+      mode,
+      durationSeconds,
+      sampleRateHz,
+      bitDepth,
+      channels,
+      dataBytes: Math.round(dataBytes),
+      fileSizeBytes: Math.round(fileSizeBytes),
+      fileSizeMB: round22(fileSizeBytes / 1e6),
+      fileSizeMiB: round22(fileSizeBytes / 1048576)
+    };
+  }
+  if (mode === "compressed") {
+    const { bitrateKbps } = input;
+    if (!Number.isFinite(bitrateKbps) || bitrateKbps <= 0) {
+      return { error: 'bitrateKbps must be a positive number for mode "compressed"' };
+    }
+    const dataBytes = bitrateKbps * 1e3 * durationSeconds / 8;
+    return {
+      mode,
+      durationSeconds,
+      bitrateKbps,
+      dataBytes: Math.round(dataBytes),
+      fileSizeBytes: Math.round(dataBytes),
+      fileSizeMB: round22(dataBytes / 1e6),
+      fileSizeMiB: round22(dataBytes / 1048576)
+    };
+  }
+  return { error: 'mode must be "pcm" or "compressed"' };
+}
 
-export { BASE_LABELS, BASE_PREFIXES, BYTE_UNITS, COMMON_CURRENCIES, COMMON_LOCALES, COMMON_PERMISSIONS, COMMON_RATIOS, COMMON_SIZES, COMMON_TAX_RATES, COMMON_TIP_PERCENTAGES, COMMON_VIEWPORTS, GPA_GRADE_POINTS, USD_DENOMINATIONS, applySuccessiveDiscounts, autoFormat, bumpVersion, calcAspectRatio, calcSubnet, calculateAnnuityPayout, calculateBlendedLoanRate, calculateBreakEven, calculateCashBreakdown, calculateCashRounding, calculateCdMaturity, calculateChange, calculateCompoundInterest, calculateCreditCardMinimumPayment, calculateCreditUtilization, calculateDebtToIncomeRatio, calculateDepreciationSchedule, calculateDiscount, calculateEmi, calculateExtraPaymentPayoff, calculateFreelancerRate, calculateGpa, calculateLoan, calculateLoanPrepaymentPenalty, calculateLoanRefinance, calculateMarginMarkup, calculateMortgagePoints, calculateMovingAverages, calculatePaybackPeriod, calculatePercentageChange, calculateRealRateOfReturn, calculateRequiredBandwidth, calculateRoi, calculateRuleOf72, calculateSalesCommission, calculateSavingsGoal, calculateSimpleInterest, calculateTax, calculateTaxEquivalentYield, calculateTimeValue, calculateTipSplit, calculateTransferTime, calculateVideoBitrate, compareSemver, compareUnitPrices, convert, convertAprApy, convertBytes, convertIp, coverBox, decimalToIp, decimalToIpCidr, describePermissions, detectNegativeAmortization, fitIntoBox, formatNumber, formatValue, formatVwValue, formatWithSeparator, gcd, intersectSemverRanges, ipFromBinary, ipFromDecimal, ipFromHex, ipToBinary, ipToDecimal, ipToDecimalCidr, ipToHex, ipToOctal, isValid, isValidCidr, isValidIp, isValidIpv4, marginToMarkup, markupToMargin, octalToPermissions, parseFileSize, parseInput, parseNumberString, parseSemver, permissionsToChmod, permissionsToOctal, permissionsToSymbolic, planDebtPayoff, ptToPx, pxToAll, pxToViewport, remToPx, satisfiesRange, scaleByHeight, scaleByWidth, sortVersions, splitSubnet, symbolicToPermissions, units_exports, validateBarcode, validateCardNumber, validateIban, validateIsbn, validateIsin, validateVin, viewportToPx };
+export { BASE_LABELS, BASE_PREFIXES, BYTE_UNITS, COMMON_CURRENCIES, COMMON_LOCALES, COMMON_PERMISSIONS, COMMON_RATIOS, COMMON_SIZES, COMMON_TAX_RATES, COMMON_TIP_PERCENTAGES, COMMON_VIEWPORTS, GPA_GRADE_POINTS, USD_DENOMINATIONS, applySuccessiveDiscounts, autoFormat, bumpVersion, calcAspectRatio, calcSubnet, calculateAnnuityPayout, calculateBlendedLoanRate, calculateBreakEven, calculateCashBreakdown, calculateCashRounding, calculateCdMaturity, calculateChange, calculateCompoundInterest, calculateCreditCardMinimumPayment, calculateCreditUtilization, calculateDebtToIncomeRatio, calculateDepreciationSchedule, calculateDiscount, calculateEmi, calculateExtraPaymentPayoff, calculateFreelancerRate, calculateGpa, calculateLoan, calculateLoanPrepaymentPenalty, calculateLoanRefinance, calculateMarginMarkup, calculateMortgagePoints, calculateMovingAverages, calculatePaybackPeriod, calculatePercentageChange, calculateRealRateOfReturn, calculateRequiredBandwidth, calculateRoi, calculateRuleOf72, calculateSalesCommission, calculateSavingsGoal, calculateSimpleInterest, calculateTax, calculateTaxEquivalentYield, calculateTimeValue, calculateTipSplit, calculateTransferTime, calculateVideoBitrate, compareSemver, compareUnitPrices, convert, convertAprApy, convertBytes, convertIp, coverBox, decimalToIp, decimalToIpCidr, describePermissions, detectNegativeAmortization, estimateAudioFileSize, fitIntoBox, formatNumber, formatValue, formatVwValue, formatWithSeparator, gcd, intersectSemverRanges, ipFromBinary, ipFromDecimal, ipFromHex, ipToBinary, ipToDecimal, ipToDecimalCidr, ipToHex, ipToOctal, isValid, isValidCidr, isValidIp, isValidIpv4, marginToMarkup, markupToMargin, octalToPermissions, parseFileSize, parseInput, parseNumberString, parseSemver, permissionsToChmod, permissionsToOctal, permissionsToSymbolic, planDebtPayoff, ptToPx, pxToAll, pxToViewport, remToPx, satisfiesRange, scaleByHeight, scaleByWidth, sortVersions, splitSubnet, symbolicToPermissions, units_exports, validateBarcode, validateCardNumber, validateIban, validateIsbn, validateIsin, validateVin, viewportToPx };

package/dist/{chunk-ZWFZRDQ4.js → chunk-YSS4VVZU.js}

@@ -13,6 +13,7 @@ __export(media_exports, {
   readPdfMetadata: () => readPdfMetadata,
   readPdfOutline: () => readPdfOutline,
   readPdfPageDimensions: () => readPdfPageDimensions,
+  readPngChunks: () => readPngChunks,
   readVideoInfo: () => readVideoInfo,
   readWavInfo: () => readWavInfo
 });
@@ -1506,5 +1507,115 @@ function readMidiInfo(bytes) {
     tracks
   };
 }
+var PNG_SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
+var PNG_CRC_TABLE = null;
+function getPngCrcTable() {
+  if (PNG_CRC_TABLE) return PNG_CRC_TABLE;
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) {
+      c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+    }
+    table[n] = c;
+  }
+  PNG_CRC_TABLE = table;
+  return table;
+}
+function pngCrc32(bytes) {
+  const table = getPngCrcTable();
+  let crc = 4294967295;
+  for (let i = 0; i < bytes.length; i++) {
+    crc = table[(crc ^ bytes[i]) & 255] ^ crc >>> 8;
+  }
+  return (crc ^ 4294967295) >>> 0;
+}
+function pad2(n) {
+  return n < 10 ? `0${n}` : `${n}`;
+}
+function readPngChunks(bytes) {
+  if (bytes.length < 8) return { error: "File too small to be a valid PNG file" };
+  for (let i = 0; i < 8; i++) {
+    if (bytes[i] !== PNG_SIGNATURE[i]) return { error: "Not a valid PNG file (bad 8-byte signature)" };
+  }
+  const chunks = [];
+  const textChunks = [];
+  let header = null;
+  let physicalDimensions = null;
+  let gamma = null;
+  let lastModified = null;
+  let isAnimated = false;
+  let offset = 8;
+  while (offset + 8 <= bytes.length) {
+    const dataLength = readU32BE(bytes, offset);
+    const type = String.fromCharCode(bytes[offset + 4], bytes[offset + 5], bytes[offset + 6], bytes[offset + 7]);
+    const dataStart = offset + 8;
+    const dataEnd = dataStart + dataLength;
+    const crcOffset = dataEnd;
+    if (crcOffset + 4 > bytes.length) {
+      return { error: `Truncated chunk "${type}" at offset ${offset}` };
+    }
+    const data = bytes.subarray(dataStart, dataEnd);
+    const expectedCrc = readU32BE(bytes, crcOffset);
+    const actualCrc = pngCrc32(bytes.subarray(offset + 4, dataEnd));
+    const firstChar = type.charCodeAt(0);
+    const critical = firstChar >= 65 && firstChar <= 90;
+    chunks.push({ type, offset, dataLength, crcValid: actualCrc === expectedCrc, critical });
+    if (type === "IHDR" && data.length >= 13) {
+      const colorTypeNum = data[9];
+      header = {
+        width: readU32BE(data, 0),
+        height: readU32BE(data, 4),
+        bitDepth: data[8],
+        colorType: PNG_COLOR_TYPES[colorTypeNum] ?? "unknown",
+        hasAlpha: colorTypeNum === 4 || colorTypeNum === 6,
+        interlace: data[12] === 1
+      };
+    } else if (type === "tEXt") {
+      const nullIdx = data.indexOf(0);
+      if (nullIdx !== -1) {
+        textChunks.push({
+          keyword: Buffer.from(data.subarray(0, nullIdx)).toString("latin1"),
+          text: Buffer.from(data.subarray(nullIdx + 1)).toString("latin1"),
+          compressed: false
+        });
+      }
+    } else if (type === "zTXt" || type === "iTXt") {
+      const nullIdx = data.indexOf(0);
+      if (nullIdx !== -1) {
+        textChunks.push({ keyword: Buffer.from(data.subarray(0, nullIdx)).toString("latin1"), text: null, compressed: true });
+      }
+    } else if (type === "pHYs" && data.length >= 9) {
+      physicalDimensions = {
+        pixelsPerUnitX: readU32BE(data, 0),
+        pixelsPerUnitY: readU32BE(data, 4),
+        unit: data[8] === 1 ? "meter" : "unknown"
+      };
+    } else if (type === "gAMA" && data.length >= 4) {
+      gamma = readU32BE(data, 0) / 1e5;
+    } else if (type === "tIME" && data.length >= 7) {
+      const year = data[0] << 8 | data[1];
+      lastModified = `${year}-${pad2(data[2])}-${pad2(data[3])}T${pad2(data[4])}:${pad2(data[5])}:${pad2(data[6])}Z`;
+    } else if (type === "acTL") {
+      isAnimated = true;
+    }
+    offset = crcOffset + 4;
+    if (type === "IEND") break;
+  }
+  if (chunks.length === 0) return { error: "No chunks found after the PNG signature" };
+  if (!header) return { error: "Missing required IHDR chunk" };
+  return {
+    valid: true,
+    fileSize: bytes.length,
+    chunkCount: chunks.length,
+    chunks,
+    header,
+    textChunks,
+    physicalDimensions,
+    gamma,
+    lastModified,
+    isAnimated
+  };
+}
 
-export { inspectGifFrames, media_exports, readExifData, readFlacInfo, readIcoInfo, readId3Tags, readImageInfo, readMidiInfo, readPdfMetadata, readPdfOutline, readPdfPageDimensions, readVideoInfo, readWavInfo };
+export { inspectGifFrames, media_exports, readExifData, readFlacInfo, readIcoInfo, readId3Tags, readImageInfo, readMidiInfo, readPdfMetadata, readPdfOutline, readPdfPageDimensions, readPngChunks, readVideoInfo, readWavInfo };

package/dist/index.cjs

@@ -9372,6 +9372,7 @@ __export(units_exports, {
   decimalToIpCidr: () => decimalToIpCidr,
   describePermissions: () => describePermissions,
   detectNegativeAmortization: () => detectNegativeAmortization,
+  estimateAudioFileSize: () => estimateAudioFileSize,
   fitIntoBox: () => fitIntoBox,
   formatNumber: () => formatNumber,
   formatValue: () => formatValue,
@@ -12468,6 +12469,56 @@ function detectNegativeAmortization(input) {
     capCrossedMonth
   };
 }
+var AUDIO_FILE_SIZE_WAV_HEADER_BYTES = 44;
+function estimateAudioFileSize(input) {
+  const { mode, durationSeconds } = input;
+  if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) {
+    return { error: "durationSeconds must be a positive number" };
+  }
+  const round23 = (n) => Math.round(n * 100) / 100;
+  if (mode === "pcm") {
+    const { sampleRateHz, bitDepth, channels } = input;
+    if (!Number.isFinite(sampleRateHz) || sampleRateHz <= 0) {
+      return { error: 'sampleRateHz must be a positive number for mode "pcm"' };
+    }
+    if (!Number.isFinite(bitDepth) || bitDepth <= 0) {
+      return { error: 'bitDepth must be a positive number for mode "pcm"' };
+    }
+    if (!Number.isInteger(channels) || channels <= 0) {
+      return { error: 'channels must be a positive whole number for mode "pcm"' };
+    }
+    const dataBytes = sampleRateHz * (bitDepth / 8) * channels * durationSeconds;
+    const fileSizeBytes = dataBytes + AUDIO_FILE_SIZE_WAV_HEADER_BYTES;
+    return {
+      mode,
+      durationSeconds,
+      sampleRateHz,
+      bitDepth,
+      channels,
+      dataBytes: Math.round(dataBytes),
+      fileSizeBytes: Math.round(fileSizeBytes),
+      fileSizeMB: round23(fileSizeBytes / 1e6),
+      fileSizeMiB: round23(fileSizeBytes / 1048576)
+    };
+  }
+  if (mode === "compressed") {
+    const { bitrateKbps } = input;
+    if (!Number.isFinite(bitrateKbps) || bitrateKbps <= 0) {
+      return { error: 'bitrateKbps must be a positive number for mode "compressed"' };
+    }
+    const dataBytes = bitrateKbps * 1e3 * durationSeconds / 8;
+    return {
+      mode,
+      durationSeconds,
+      bitrateKbps,
+      dataBytes: Math.round(dataBytes),
+      fileSizeBytes: Math.round(dataBytes),
+      fileSizeMB: round23(dataBytes / 1e6),
+      fileSizeMiB: round23(dataBytes / 1048576)
+    };
+  }
+  return { error: 'mode must be "pcm" or "compressed"' };
+}
 
 // src/tools/network.ts
 var network_exports = {};
@@ -27334,6 +27385,7 @@ __export(media_exports, {
   readPdfMetadata: () => readPdfMetadata,
   readPdfOutline: () => readPdfOutline,
   readPdfPageDimensions: () => readPdfPageDimensions,
+  readPngChunks: () => readPngChunks,
   readVideoInfo: () => readVideoInfo,
   readWavInfo: () => readWavInfo
 });
@@ -28827,6 +28879,116 @@ function readMidiInfo(bytes) {
     tracks
   };
 }
+var PNG_SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
+var PNG_CRC_TABLE = null;
+function getPngCrcTable() {
+  if (PNG_CRC_TABLE) return PNG_CRC_TABLE;
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) {
+      c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+    }
+    table[n] = c;
+  }
+  PNG_CRC_TABLE = table;
+  return table;
+}
+function pngCrc32(bytes) {
+  const table = getPngCrcTable();
+  let crc = 4294967295;
+  for (let i = 0; i < bytes.length; i++) {
+    crc = table[(crc ^ bytes[i]) & 255] ^ crc >>> 8;
+  }
+  return (crc ^ 4294967295) >>> 0;
+}
+function pad2(n) {
+  return n < 10 ? `0${n}` : `${n}`;
+}
+function readPngChunks(bytes) {
+  if (bytes.length < 8) return { error: "File too small to be a valid PNG file" };
+  for (let i = 0; i < 8; i++) {
+    if (bytes[i] !== PNG_SIGNATURE[i]) return { error: "Not a valid PNG file (bad 8-byte signature)" };
+  }
+  const chunks = [];
+  const textChunks = [];
+  let header = null;
+  let physicalDimensions = null;
+  let gamma = null;
+  let lastModified = null;
+  let isAnimated = false;
+  let offset = 8;
+  while (offset + 8 <= bytes.length) {
+    const dataLength = readU32BE(bytes, offset);
+    const type = String.fromCharCode(bytes[offset + 4], bytes[offset + 5], bytes[offset + 6], bytes[offset + 7]);
+    const dataStart = offset + 8;
+    const dataEnd = dataStart + dataLength;
+    const crcOffset = dataEnd;
+    if (crcOffset + 4 > bytes.length) {
+      return { error: `Truncated chunk "${type}" at offset ${offset}` };
+    }
+    const data = bytes.subarray(dataStart, dataEnd);
+    const expectedCrc = readU32BE(bytes, crcOffset);
+    const actualCrc = pngCrc32(bytes.subarray(offset + 4, dataEnd));
+    const firstChar = type.charCodeAt(0);
+    const critical = firstChar >= 65 && firstChar <= 90;
+    chunks.push({ type, offset, dataLength, crcValid: actualCrc === expectedCrc, critical });
+    if (type === "IHDR" && data.length >= 13) {
+      const colorTypeNum = data[9];
+      header = {
+        width: readU32BE(data, 0),
+        height: readU32BE(data, 4),
+        bitDepth: data[8],
+        colorType: PNG_COLOR_TYPES[colorTypeNum] ?? "unknown",
+        hasAlpha: colorTypeNum === 4 || colorTypeNum === 6,
+        interlace: data[12] === 1
+      };
+    } else if (type === "tEXt") {
+      const nullIdx = data.indexOf(0);
+      if (nullIdx !== -1) {
+        textChunks.push({
+          keyword: Buffer.from(data.subarray(0, nullIdx)).toString("latin1"),
+          text: Buffer.from(data.subarray(nullIdx + 1)).toString("latin1"),
+          compressed: false
+        });
+      }
+    } else if (type === "zTXt" || type === "iTXt") {
+      const nullIdx = data.indexOf(0);
+      if (nullIdx !== -1) {
+        textChunks.push({ keyword: Buffer.from(data.subarray(0, nullIdx)).toString("latin1"), text: null, compressed: true });
+      }
+    } else if (type === "pHYs" && data.length >= 9) {
+      physicalDimensions = {
+        pixelsPerUnitX: readU32BE(data, 0),
+        pixelsPerUnitY: readU32BE(data, 4),
+        unit: data[8] === 1 ? "meter" : "unknown"
+      };
+    } else if (type === "gAMA" && data.length >= 4) {
+      gamma = readU32BE(data, 0) / 1e5;
+    } else if (type === "tIME" && data.length >= 7) {
+      const year = data[0] << 8 | data[1];
+      lastModified = `${year}-${pad2(data[2])}-${pad2(data[3])}T${pad2(data[4])}:${pad2(data[5])}:${pad2(data[6])}Z`;
+    } else if (type === "acTL") {
+      isAnimated = true;
+    }
+    offset = crcOffset + 4;
+    if (type === "IEND") break;
+  }
+  if (chunks.length === 0) return { error: "No chunks found after the PNG signature" };
+  if (!header) return { error: "Missing required IHDR chunk" };
+  return {
+    valid: true,
+    fileSize: bytes.length,
+    chunkCount: chunks.length,
+    chunks,
+    header,
+    textChunks,
+    physicalDimensions,
+    gamma,
+    lastModified,
+    isAnimated
+  };
+}
 
 // src/index.ts
 var version = "0.1.0";

package/dist/index.d.cts

@@ -5,7 +5,7 @@ export { t as text } from './text-DOopHoK3.cjs';
 export { d as data } from './data-3qMdFIF5.cjs';
 export { g as generators } from './generators-DAXXrMvG.cjs';
 export { t as time } from './time-VMAy_SrV.cjs';
-export { u as units } from './units-DnWrOTSV.cjs';
+export { u as units } from './units-BBzv0VIt.cjs';
 export { n as network } from './network-B6fQrsCc.cjs';
 export { a as api } from './api-CQnIUrVB.cjs';
 export { c as code } from './code-CZHElFHu.cjs';
@@ -13,7 +13,7 @@ export { c as color } from './color-tPwZCr9H.cjs';
 export { c as css } from './css-Cf7AMGM-.cjs';
 export { m as misc } from './misc-CA3N198T.cjs';
 export { a as ai_agent } from './ai_agent-B9wWLBDf.cjs';
-export { m as media } from './media-DF8BS-iA.cjs';
+export { m as media } from './media-C8Y67lUI.cjs';
 
 declare const version = "0.1.0";
 

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { t as text } from './text-DOopHoK3.js';
 export { d as data } from './data-3qMdFIF5.js';
 export { g as generators } from './generators-DAXXrMvG.js';
 export { t as time } from './time-VMAy_SrV.js';
-export { u as units } from './units-DnWrOTSV.js';
+export { u as units } from './units-BBzv0VIt.js';
 export { n as network } from './network-B6fQrsCc.js';
 export { a as api } from './api-CQnIUrVB.js';
 export { c as code } from './code-CZHElFHu.js';
@@ -13,7 +13,7 @@ export { c as color } from './color-tPwZCr9H.js';
 export { c as css } from './css-Cf7AMGM-.js';
 export { m as misc } from './misc-CA3N198T.js';
 export { a as ai_agent } from './ai_agent-B9wWLBDf.js';
-export { m as media } from './media-DF8BS-iA.js';
+export { m as media } from './media-C8Y67lUI.js';
 
 declare const version = "0.1.0";
 

package/dist/index.js

@@ -1,5 +1,5 @@
-export { media_exports as media } from './chunk-ZWFZRDQ4.js';
-export { units_exports as units } from './chunk-XAPHAUPI.js';
+export { media_exports as media } from './chunk-YSS4VVZU.js';
+export { units_exports as units } from './chunk-G5NUC5MV.js';
 export { network_exports as network } from './chunk-K242OOF4.js';
 export { api_exports as api } from './chunk-U2HREMZU.js';
 export { code_exports as code } from './chunk-KRPIOHJ4.js';

package/dist/{media-DF8BS-iA.d.cts → media-C8Y67lUI.d.cts}

@@ -289,6 +289,59 @@ interface MidiInfoError {
  * frames-per-second/ticks-per-frame rate instead.
  */
 declare function readMidiInfo(bytes: Uint8Array): MidiInfo | MidiInfoError;
+interface PngChunkEntry {
+    type: string;
+    offset: number;
+    dataLength: number;
+    crcValid: boolean;
+    /** A chunk type is "critical" (decoders must understand it) when its
+     *  first letter is uppercase, e.g. IHDR vs. an ancillary tEXt. */
+    critical: boolean;
+}
+interface PngHeaderInfo {
+    width: number;
+    height: number;
+    bitDepth: number;
+    colorType: string;
+    hasAlpha: boolean;
+    interlace: boolean;
+}
+interface PngTextChunk {
+    keyword: string;
+    text: string | null;
+    /** True for zTXt/iTXt, whose text this function does not decode. */
+    compressed: boolean;
+}
+interface PngPhysicalDimensions {
+    pixelsPerUnitX: number;
+    pixelsPerUnitY: number;
+    unit: 'meter' | 'unknown';
+}
+interface PngChunkInfo {
+    valid: true;
+    fileSize: number;
+    chunkCount: number;
+    chunks: PngChunkEntry[];
+    header: PngHeaderInfo | null;
+    textChunks: PngTextChunk[];
+    physicalDimensions: PngPhysicalDimensions | null;
+    gamma: number | null;
+    lastModified: string | null;
+    isAnimated: boolean;
+}
+interface PngChunkInfoError {
+    error: string;
+}
+/**
+ * Walk a PNG file's full chunk stream directly from its bytes: every
+ * chunk's type, byte offset, data length, and whether its stored CRC-32
+ * matches the type+data it covers, plus the decoded IHDR header and a
+ * handful of common ancillary chunks (tEXt, pHYs, gAMA, tIME, and acTL for
+ * APNG animation). No image library or pixel decoding is involved, and
+ * zTXt/iTXt text is listed but not zlib-inflated, so the result is
+ * identical in a browser tool and on a server.
+ */
+declare function readPngChunks(bytes: Uint8Array): PngChunkInfo | PngChunkInfoError;
 
 type media_ExifData = ExifData;
 type media_ExifError = ExifError;
@@ -318,6 +371,12 @@ type media_PdfOutlineResult = PdfOutlineResult;
 type media_PdfPageDimension = PdfPageDimension;
 type media_PdfPageDimensionsResult = PdfPageDimensionsResult;
 type media_PdfPageOrientation = PdfPageOrientation;
+type media_PngChunkEntry = PngChunkEntry;
+type media_PngChunkInfo = PngChunkInfo;
+type media_PngChunkInfoError = PngChunkInfoError;
+type media_PngHeaderInfo = PngHeaderInfo;
+type media_PngPhysicalDimensions = PngPhysicalDimensions;
+type media_PngTextChunk = PngTextChunk;
 type media_VideoInfo = VideoInfo;
 type media_VideoInfoError = VideoInfoError;
 type media_WavInfo = WavInfo;
@@ -332,10 +391,11 @@ declare const media_readMidiInfo: typeof readMidiInfo;
 declare const media_readPdfMetadata: typeof readPdfMetadata;
 declare const media_readPdfOutline: typeof readPdfOutline;
 declare const media_readPdfPageDimensions: typeof readPdfPageDimensions;
+declare const media_readPngChunks: typeof readPngChunks;
 declare const media_readVideoInfo: typeof readVideoInfo;
 declare const media_readWavInfo: typeof readWavInfo;
 declare namespace media {
-  export { type media_ExifData as ExifData, type media_ExifError as ExifError, type media_FlacInfo as FlacInfo, type media_FlacInfoError as FlacInfoError, type media_GifInfo as GifInfo, type media_GifInfoError as GifInfoError, type media_IcoImageEntry as IcoImageEntry, type media_IcoInfo as IcoInfo, type media_IcoInfoError as IcoInfoError, type media_Id3Tags as Id3Tags, type media_Id3TagsError as Id3TagsError, type media_ImageFormat as ImageFormat, type media_ImageInfo as ImageInfo, type media_ImageInfoError as ImageInfoError, type media_MidiDivision as MidiDivision, type media_MidiInfo as MidiInfo, type media_MidiInfoError as MidiInfoError, type media_MidiTimeSignature as MidiTimeSignature, type media_MidiTrackInfo as MidiTrackInfo, type media_PdfMetadata as PdfMetadata, type media_PdfMetadataError as PdfMetadataError, type media_PdfOutlineDestType as PdfOutlineDestType, type media_PdfOutlineError as PdfOutlineError, type media_PdfOutlineItem as PdfOutlineItem, type media_PdfOutlineResult as PdfOutlineResult, type media_PdfPageDimension as PdfPageDimension, type media_PdfPageDimensionsResult as PdfPageDimensionsResult, type media_PdfPageOrientation as PdfPageOrientation, type media_VideoInfo as VideoInfo, type media_VideoInfoError as VideoInfoError, type media_WavInfo as WavInfo, type media_WavInfoError as WavInfoError, media_inspectGifFrames as inspectGifFrames, media_readExifData as readExifData, media_readFlacInfo as readFlacInfo, media_readIcoInfo as readIcoInfo, media_readId3Tags as readId3Tags, media_readImageInfo as readImageInfo, media_readMidiInfo as readMidiInfo, media_readPdfMetadata as readPdfMetadata, media_readPdfOutline as readPdfOutline, media_readPdfPageDimensions as readPdfPageDimensions, media_readVideoInfo as readVideoInfo, media_readWavInfo as readWavInfo };
+  export { type media_ExifData as ExifData, type media_ExifError as ExifError, type media_FlacInfo as FlacInfo, type media_FlacInfoError as FlacInfoError, type media_GifInfo as GifInfo, type media_GifInfoError as GifInfoError, type media_IcoImageEntry as IcoImageEntry, type media_IcoInfo as IcoInfo, type media_IcoInfoError as IcoInfoError, type media_Id3Tags as Id3Tags, type media_Id3TagsError as Id3TagsError, type media_ImageFormat as ImageFormat, type media_ImageInfo as ImageInfo, type media_ImageInfoError as ImageInfoError, type media_MidiDivision as MidiDivision, type media_MidiInfo as MidiInfo, type media_MidiInfoError as MidiInfoError, type media_MidiTimeSignature as MidiTimeSignature, type media_MidiTrackInfo as MidiTrackInfo, type media_PdfMetadata as PdfMetadata, type media_PdfMetadataError as PdfMetadataError, type media_PdfOutlineDestType as PdfOutlineDestType, type media_PdfOutlineError as PdfOutlineError, type media_PdfOutlineItem as PdfOutlineItem, type media_PdfOutlineResult as PdfOutlineResult, type media_PdfPageDimension as PdfPageDimension, type media_PdfPageDimensionsResult as PdfPageDimensionsResult, type media_PdfPageOrientation as PdfPageOrientation, type media_PngChunkEntry as PngChunkEntry, type media_PngChunkInfo as PngChunkInfo, type media_PngChunkInfoError as PngChunkInfoError, type media_PngHeaderInfo as PngHeaderInfo, type media_PngPhysicalDimensions as PngPhysicalDimensions, type media_PngTextChunk as PngTextChunk, type media_VideoInfo as VideoInfo, type media_VideoInfoError as VideoInfoError, type media_WavInfo as WavInfo, type media_WavInfoError as WavInfoError, media_inspectGifFrames as inspectGifFrames, media_readExifData as readExifData, media_readFlacInfo as readFlacInfo, media_readIcoInfo as readIcoInfo, media_readId3Tags as readId3Tags, media_readImageInfo as readImageInfo, media_readMidiInfo as readMidiInfo, media_readPdfMetadata as readPdfMetadata, media_readPdfOutline as readPdfOutline, media_readPdfPageDimensions as readPdfPageDimensions, media_readPngChunks as readPngChunks, media_readVideoInfo as readVideoInfo, media_readWavInfo as readWavInfo };
 }
 
-export { readExifData as A, readFlacInfo as B, readIcoInfo as C, readId3Tags as D, type ExifData as E, type FlacInfo as F, type GifInfo as G, readImageInfo as H, type IcoImageEntry as I, readMidiInfo as J, readPdfMetadata as K, readPdfOutline as L, type MidiDivision as M, readPdfPageDimensions as N, readVideoInfo as O, type PdfMetadata as P, readWavInfo as Q, type VideoInfo as V, type WavInfo as W, type ExifError as a, type FlacInfoError as b, type GifInfoError as c, type IcoInfo as d, type IcoInfoError as e, type Id3Tags as f, type Id3TagsError as g, type ImageFormat as h, type ImageInfo as i, type ImageInfoError as j, type MidiInfo as k, type MidiInfoError as l, media as m, type MidiTimeSignature as n, type MidiTrackInfo as o, type PdfMetadataError as p, type PdfOutlineDestType as q, type PdfOutlineError as r, type PdfOutlineItem as s, type PdfOutlineResult as t, type PdfPageDimension as u, type PdfPageDimensionsResult as v, type PdfPageOrientation as w, type VideoInfoError as x, type WavInfoError as y, inspectGifFrames as z };
+export { type PngHeaderInfo as A, type PngPhysicalDimensions as B, type PngTextChunk as C, type VideoInfoError as D, type ExifData as E, type FlacInfo as F, type GifInfo as G, type WavInfoError as H, type IcoImageEntry as I, inspectGifFrames as J, readExifData as K, readFlacInfo as L, type MidiDivision as M, readIcoInfo as N, readId3Tags as O, type PdfMetadata as P, readImageInfo as Q, readMidiInfo as R, readPdfMetadata as S, readPdfOutline as T, readPdfPageDimensions as U, type VideoInfo as V, type WavInfo as W, readPngChunks as X, readVideoInfo as Y, readWavInfo as Z, type ExifError as a, type FlacInfoError as b, type GifInfoError as c, type IcoInfo as d, type IcoInfoError as e, type Id3Tags as f, type Id3TagsError as g, type ImageFormat as h, type ImageInfo as i, type ImageInfoError as j, type MidiInfo as k, type MidiInfoError as l, media as m, type MidiTimeSignature as n, type MidiTrackInfo as o, type PdfMetadataError as p, type PdfOutlineDestType as q, type PdfOutlineError as r, type PdfOutlineItem as s, type PdfOutlineResult as t, type PdfPageDimension as u, type PdfPageDimensionsResult as v, type PdfPageOrientation as w, type PngChunkEntry as x, type PngChunkInfo as y, type PngChunkInfoError as z };