ravensight-playtest 0.5.2 → 0.7.0

package/src/api/client.js

@@ -14,6 +14,15 @@ function gameBase(gameId) {
   return `/api/v1/games/${encodeURIComponent(gameId)}/playtest`;
 }
 
+/** `/api/v1/games/:gameId/labs/lists/:list`, for the punch list and blue tape. */
+function labsListBase(gameId, list) {
+  if (typeof gameId !== 'string' || gameId.length === 0) {
+    throw new TypeError('gameId is required');
+  }
+  if (list !== 'punch' && list !== 'tape') throw new TypeError('list must be punch or tape');
+  return `/api/v1/games/${encodeURIComponent(gameId)}/labs/lists/${list}`;
+}
+
 /**
  * The Ravensight playtest API, as one object with one namespace per surface.
  *
@@ -195,9 +204,9 @@ export function createClient(options = {}) {
      * persona run's price; anything else leaves `run_length` out, which the
      * server reads as a standard run.
      */
-    estimate: (gameId, { modules = [], personas = [], runLength = null, simulation, controllers, driver } = {}) =>
+    estimate: (gameId, { modules = [], personas = [], runLength = null, simulation, controllers, driver, validate, feature, acceptance } = {}) =>
       request('POST', `${gameBase(gameId)}/estimate`, {
-        body: { modules, personas, ...(controllers ? { controllers, driver } : {}), ...(runLength === 'long' ? { run_length: 'long' } : {}), ...(simulation ? { simulation } : {}) }
+        body: { modules, personas, ...(controllers ? { controllers, driver } : {}), ...(runLength === 'long' ? { run_length: 'long' } : {}), ...(simulation ? { simulation } : {}), ...(validate ? { validate } : {}), ...(feature ? { feature } : {}), ...(acceptance ? { acceptance: true } : {}) }
       }).then(answer => answer.body),
 
     /**
@@ -238,6 +247,11 @@ export function createClient(options = {}) {
         body: { state, reason }
       }).then(answer => answer.body),
 
+    /** What became of the pull request a Labs job opened. Feedback, no money. */
+    labsOutcomePr: (gameId, jobId, { pr }) =>
+      request('PUT', `${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}/labs-outcome/pr`, { body: { pr } })
+        .then(answer => answer.body),
+
     remove: (gameId, jobId) =>
       request('DELETE', `${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}`).then(() => undefined),
 
@@ -267,6 +281,17 @@ export function createClient(options = {}) {
       request('POST', `${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}/fix/triage`, { body })
         .then(answer => answer.body),
 
+    /** A validate job's comparison, computed by the server from its run rows. */
+    validation: (gameId, jobId) =>
+      get(`${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}/validation`),
+
+    validationMarkdown: async (gameId, jobId) =>
+      (await request('GET', `${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}/validation`, { query: { format: 'md' }, raw: true, idempotent: true })).body,
+
+    /** A feature job's report, computed by the server from its run rows. */
+    feature: (gameId, jobId) =>
+      get(`${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}/feature`),
+
     artifacts: (gameId, jobId) =>
       get(`${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}/artifacts`),
 
@@ -301,6 +326,16 @@ export function createClient(options = {}) {
      */
     get: (gameId, jobId, runId) => get(runPath(gameId, jobId, runId)),
 
+    /** More pairs on a validate job: a separate, confirmed purchase. */
+    addValidatePairs: (gameId, jobId, pairs) =>
+      request('POST', `${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}/runs`, {
+        body: { validate_pairs: pairs }
+      }).then(answer => answer.body),
+
+    /** Record a trace replay. Free; the per-job cap answers 409 `replay_cap_reached`. */
+    recordReplay: (gameId, jobId, runId, report) =>
+      request('POST', runPath(gameId, jobId, runId, '/replays'), { body: report }).then(answer => answer.body),
+
     add: (gameId, jobId, personas) =>
       request('POST', `${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}/runs`, {
         body: { personas }
@@ -366,5 +401,87 @@ export function createClient(options = {}) {
       })).body
   };
 
-  return { apiUrl, token, cliVersion, request, cli, packs, brief, jobs, runs };
+  /**
+   * Ravensight Labs. `get` answers which Labs capabilities are live for the
+   * game; an older server has no such route, which callers read as "off".
+   */
+  const labs = {
+    get: gameId => {
+      if (typeof gameId !== 'string' || gameId.length === 0) throw new TypeError('gameId is required');
+      return get(`/api/v1/games/${encodeURIComponent(gameId)}/labs`);
+    },
+
+    /**
+     * Build a feature specifications. Writing one is one AI unit; reading is
+     * free. Editing and approving are the dashboard's, on purpose: this token
+     * cannot do either.
+     */
+    /**
+     * The punch list and blue tape. `list` is `punch` or `tape`. Reads and
+     * plain writes are free; `draft` is one AI unit and saves nothing.
+     */
+    lists: {
+      list: (gameId, list, { status } = {}) =>
+        get(labsListBase(gameId, list), { query: status ? { status } : undefined }),
+      get: (gameId, list, itemId) =>
+        get(`${labsListBase(gameId, list)}/items/${encodeURIComponent(itemId)}`),
+      add: (gameId, list, body) =>
+        request('POST', labsListBase(gameId, list), { body }).then(answer => answer.body),
+      update: (gameId, list, itemId, body) =>
+        request('PATCH', `${labsListBase(gameId, list)}/items/${encodeURIComponent(itemId)}`, { body }).then(answer => answer.body),
+      promote: (gameId, itemId) =>
+        request('POST', `${labsListBase(gameId, 'tape')}/items/${encodeURIComponent(itemId)}/promote`, { body: {} }).then(answer => answer.body),
+      draft: gameId =>
+        request('POST', `${labsListBase(gameId, 'punch')}/draft`, { body: {} }).then(answer => answer.body)
+    },
+
+    featureSpecs: {
+      create: (gameId, brief, extra = {}) =>
+        request('POST', `/api/v1/games/${encodeURIComponent(gameId)}/labs/feature-specs`, { body: { brief, ...extra } }).then(answer => answer.body),
+      get: (gameId, specId) =>
+        get(`/api/v1/games/${encodeURIComponent(gameId)}/labs/feature-specs/${encodeURIComponent(specId)}`)
+    },
+
+    /**
+     * Create a game (Labs, Experimental). The quote comes before any game exists,
+     * so it is org-scoped. Approving and rejecting a design are the dashboard's, on
+     * purpose: this token cannot do either.
+     */
+    prototypes: {
+      estimate: ({ milestones, size }) =>
+        get(`/api/v1/labs/prototype/estimate?milestones=${encodeURIComponent(milestones)}&size=${encodeURIComponent(size)}`),
+      createGame: ({ gameId, name }) =>
+        request('POST', '/api/v1/games', { body: { gameId, name, engine: 'godot', labs_prototype: true } }).then(answer => answer.body),
+      get: (gameId, jobId) =>
+        get(`/api/v1/games/${encodeURIComponent(gameId)}/labs/prototypes/${encodeURIComponent(jobId)}`),
+      submitDesign: (gameId, jobId, design) =>
+        request('POST', `/api/v1/games/${encodeURIComponent(gameId)}/labs/prototypes/${encodeURIComponent(jobId)}/design`, { body: { design } }).then(answer => answer.body),
+      stop: (gameId, jobId) =>
+        request('POST', `/api/v1/games/${encodeURIComponent(gameId)}/labs/prototypes/${encodeURIComponent(jobId)}/stop`, { body: {} }).then(answer => answer.body),
+      playable: (gameId, jobId, body) =>
+        request('POST', `/api/v1/games/${encodeURIComponent(gameId)}/labs/prototypes/${encodeURIComponent(jobId)}/playable`, { body }).then(answer => answer.body)
+    }
+  };
+
+  // Hosted comparison. A spending call carries the caller's Idempotency-Key, so a
+  // retry cannot start a second one.
+  const hosted = {
+    capabilities: gameId => get(`${gameBase(gameId)}/hosted/capabilities`),
+    builds: gameId => get(`${gameBase(gameId)}/hosted/builds`),
+    createBuild: (gameId, body, idempotencyKey) =>
+      request('POST', `${gameBase(gameId)}/hosted/builds`, { body, headers: { 'idempotency-key': idempotencyKey } }).then(answer => answer.body),
+    completeBuild: (gameId, buildId) =>
+      request('POST', `${gameBase(gameId)}/hosted/builds/${encodeURIComponent(buildId)}/complete`, { body: {} }).then(answer => answer.body),
+    deleteBuild: (gameId, buildId) =>
+      request('DELETE', `${gameBase(gameId)}/hosted/builds/${encodeURIComponent(buildId)}`).then(answer => answer.body),
+    quotePair: (gameId, body) =>
+      request('POST', `${gameBase(gameId)}/hosted/validate-pairs/quotes`, { body }).then(answer => answer.body),
+    createPair: (gameId, body, idempotencyKey) =>
+      request('POST', `${gameBase(gameId)}/hosted/validate-pairs`, { body, headers: { 'idempotency-key': idempotencyKey } }).then(answer => answer.body),
+    readPair: (gameId, pairId) => get(`${gameBase(gameId)}/hosted/validate-pairs/${encodeURIComponent(pairId)}`),
+    cancelPair: (gameId, pairId) =>
+      request('POST', `${gameBase(gameId)}/hosted/validate-pairs/${encodeURIComponent(pairId)}/cancel`, { body: {} }).then(answer => answer.body)
+  };
+
+  return { apiUrl, token, cliVersion, request, cli, packs, brief, jobs, runs, labs, hosted };
 }

package/src/api/errors.js

@@ -65,9 +65,25 @@ const RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
  * answer (a replay, or a charge) within a few seconds. Only retried when it
  * actually carries a `Retry-After`: without one there is no interval the
  * server has blessed, and guessing at a money path is not this layer's call.
+ *
+ * `settle_contended` is a 409 from the same family, and one that says outright
+ * that the job changed underneath the settle and nothing moved. So it is the one
+ * code safe to repeat on a POST that carries no idempotency key: see
+ * `nothingMoved`. The sweep settles the job if every try is contended.
  */
 const NEVER_RETRY_CODES = new Set(['too_many_active_jobs']);
-const CODE_RETRY_LIMITS = new Map([['charge_in_progress', 5]]);
+const CODE_RETRY_LIMITS = new Map([['charge_in_progress', 5], ['settle_contended', 4]]);
+const NOTHING_MOVED_CODES = new Set(['settle_contended']);
+
+/**
+ * Whether this refusal promises that repeating the request cannot move money
+ * twice, whatever the method.
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function nothingMoved(error) {
+  return error instanceof ApiError && NOTHING_MOVED_CODES.has(error.code);
+}
 
 /**
  * How many retries this error's own code is allowed, independent of the

package/src/api/http.js

@@ -1,4 +1,4 @@
-import { ApiError, codeRetryLimit, isRetryable, parseRetryAfter } from './errors.js';
+import { ApiError, codeRetryLimit, isRetryable, nothingMoved, parseRetryAfter } from './errors.js';
 
 export const DEFAULT_RETRIES = 4;
 export const DEFAULT_TIMEOUT_MS = 30000;
@@ -42,12 +42,18 @@ export function buildUrl(apiUrl, path, query) {
   return url.toString();
 }
 
+/** Carries a capture hook's own error past the request loop's network catch. */
+class CaptureFailure {
+  constructor(error) { this.error = error; }
+}
+
 /**
  * Read a response body without throwing for body or JSON decoding errors. A 502 from a load balancer is
  * HTML, a 204 is empty, and a JSON parse failure on the error path would
- * replace a useful status code with a useless SyntaxError.
+ * replace a useful status code with a useless SyntaxError. `cut` says the connection
+ * went before the body finished, which is not the same as an empty body.
  * @param {Response} response
- * @returns {Promise<{json: unknown, text: string}>}
+ * @returns {Promise<{json: unknown, text: string, cut?: Error}>}
  */
 async function readBody(response, onResponseRaw) {
   let text = '';
@@ -57,12 +63,22 @@ async function readBody(response, onResponseRaw) {
     catch { /* Preserve a read-failure observation, never invent complete bytes. */ }
     // Opt-in capture runs on every HTTP status BEFORE JSON parsing or an
     // ApiError. Capture failures propagate and cannot trigger a request retry.
-    await onResponseRaw({ status: response.status, contentType: response.headers.get('content-type'), bytes, bodyComplete });
+    try {
+      await onResponseRaw({ status: response.status, contentType: response.headers.get('content-type'), bytes, bodyComplete });
+    } catch (error) {
+      throw new CaptureFailure(error);
+    }
+    // A capture caller owns an incomplete body: the observation says so, and it
+    // must decide from that record (an admission never POSTs again on an unknown
+    // outcome), so this is not turned into a retryable network error.
     if (!bodyComplete) return { json: null, text: '' };
     text = new TextDecoder().decode(bytes);
   } else {
-    try { text = await response.text(); }
-    catch { return { json: null, text: '' }; }
+    try {
+      text = await response.text();
+    } catch (cause) {
+      return { json: null, text: '', cut: cause };
+    }
   }
   if (!text) return { json: null, text: '' };
   try {
@@ -95,7 +111,8 @@ function errorFrom(response, parsed, { method, path }) {
  * Retries cover a network failure, a timeout, 408, 425, 429 and 5xx, plus the
  * two error codes whose status alone gives the wrong answer (see
  * `codeRetryLimit`): `charge_in_progress` is retried on its own `Retry-After`
- * although it is a 409, and `too_many_active_jobs` is not retried although it
+ * although it is a 409, `settle_contended` likewise and on any method because it
+ * promises nothing moved, and `too_many_active_jobs` is not retried although it
  * is a 429. A mutation is only ever retried when the caller says
  * `idempotent: true`, which in practice means a GET, a heartbeat, or a POST
  * carrying an `Idempotency-Key` the server uses to replay rather than repeat.
@@ -150,7 +167,16 @@ export async function requestWithRetry(options) {
   for (let attempt = 1; ; attempt += 1) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const unreachable = cause => new ApiError({
+      status: 0,
+      code: 'network_error',
+      message: `${method} ${path} could not reach ${new URL(url).host}: ${cause.message}`,
+      method,
+      path,
+      cause
+    });
     let response = null;
+    let parsed = null;
     try {
       response = await fetchImpl(url, {
         method,
@@ -158,21 +184,21 @@ export async function requestWithRetry(options) {
         body: bodyText === undefined ? undefined : bodyText,
         signal: controller.signal
       });
+      // The time limit covers the body too, and a success whose body never finished
+      // is no answer: reading it as an empty 200 lost the job id of a job just charged.
+      parsed = await readBody(response, onResponseRaw);
+      if (parsed.cut) {
+        lastError = unreachable(parsed.cut);
+        response = null;
+      }
     } catch (cause) {
-      lastError = new ApiError({
-        status: 0,
-        code: 'network_error',
-        message: `${method} ${path} could not reach ${new URL(url).host}: ${cause.message}`,
-        method,
-        path,
-        cause
-      });
+      if (cause instanceof CaptureFailure) throw cause.error;
+      lastError = unreachable(cause);
     } finally {
       clearTimeout(timer);
     }
 
     if (response) {
-      const parsed = await readBody(response, onResponseRaw);
       if (response.ok || response.status === 304) {
         return {
           status: response.status,
@@ -183,7 +209,7 @@ export async function requestWithRetry(options) {
       lastError = errorFrom(response, parsed, { method, path });
     }
 
-    if (!retryable) throw lastError;
+    if (!retryable && !nothingMoved(lastError)) throw lastError;
 
     const limit = codeRetryLimit(lastError);
     let canRetry;

package/src/assets/formats.js

@@ -0,0 +1,267 @@
+import { inflateSync } from 'node:zlib';
+
+/**
+ * Plain parsers for the three formats the inventory measures closely: PNG, WAV
+ * and Ogg. No dependency, because this runs inside a CLI that ships with few, and
+ * none of these needs more than a header and, for PNG, one inflate.
+ *
+ * Each parser answers what it read and `problem` when the file is damaged, and
+ * never throws on hostile bytes: a studio's folder can hold anything.
+ */
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+/** Above this the pixels are not decoded: the header still answers the size. */
+export const MAX_DECODED_PIXELS = 64 * 1024 * 1024;
+
+const CHANNELS = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+const VALID_DEPTHS = { 0: [1, 2, 4, 8, 16], 2: [8, 16], 3: [1, 2, 4, 8], 4: [8, 16], 6: [8, 16] };
+
+/**
+ * The PNG's chunks up to IEND, without decoding the pixels.
+ *
+ * @param {Buffer} data
+ * @returns {{width: number, height: number, bitDepth: number, colorType: number, interlaced: boolean, palette: Buffer|null, transparency: Buffer|null, idat: Buffer[], problem: string|null}|null} null when it is not a PNG at all
+ */
+export function readPngHeader(data) {
+  if (data.length < 33 || !data.subarray(0, 8).equals(PNG_SIGNATURE)) return null;
+  const out = { width: 0, height: 0, bitDepth: 0, colorType: 0, interlaced: false, palette: null, transparency: null, idat: [], problem: null };
+  let at = 8;
+  let sawHeader = false;
+  let sawEnd = false;
+  while (at + 8 <= data.length) {
+    const length = data.readUInt32BE(at);
+    const type = data.toString('latin1', at + 4, at + 8);
+    const start = at + 8;
+    if (start + length > data.length) {
+      out.problem = `the ${type} chunk runs past the end of the file`;
+      break;
+    }
+    const body = data.subarray(start, start + length);
+    if (type === 'IHDR') {
+      if (length < 13) return { ...out, problem: 'the image header is too short' };
+      out.width = body.readUInt32BE(0);
+      out.height = body.readUInt32BE(4);
+      out.bitDepth = body[8];
+      out.colorType = body[9];
+      out.interlaced = body[12] === 1;
+      sawHeader = true;
+    } else if (type === 'PLTE') out.palette = body;
+    else if (type === 'tRNS') out.transparency = body;
+    else if (type === 'IDAT') out.idat.push(body);
+    else if (type === 'IEND') { sawEnd = true; break; }
+    at = start + length + 4;
+  }
+  if (!sawHeader) return { ...out, problem: out.problem || 'there is no image header' };
+  if (!(VALID_DEPTHS[out.colorType] || []).includes(out.bitDepth)) return { ...out, problem: 'the colour type and bit depth are not valid together' };
+  if (!sawEnd && !out.problem) out.problem = 'the file ends before the image does';
+  return out;
+}
+
+/** The Paeth predictor, from the PNG specification. */
+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);
+  if (pa <= pb && pa <= pc) return a;
+  return pb <= pc ? b : c;
+}
+
+/**
+ * Decode a non-interlaced PNG to 8-bit RGBA.
+ *
+ * @param {ReturnType<typeof readPngHeader>} header
+ * @returns {{width: number, height: number, rgba: Uint8Array}|{problem: string}|null} null for what is
+ *   not decoded on purpose: interlaced, or over MAX_DECODED_PIXELS
+ */
+export function decodePng(header) {
+  const { width, height, bitDepth, colorType } = header;
+  if (header.interlaced || width * height > MAX_DECODED_PIXELS || width * height === 0) return null;
+  const channels = CHANNELS[colorType];
+  const stride = Math.ceil((width * channels * bitDepth) / 8);
+  const bytesPerPixel = Math.max(1, (channels * bitDepth) >> 3);
+  const expected = (stride + 1) * height;
+  let raw;
+  try {
+    raw = inflateSync(Buffer.concat(header.idat), { maxOutputLength: expected + 1024 });
+  } catch {
+    return { problem: 'the pixel data does not decompress' };
+  }
+  if (raw.length < expected) return { problem: 'the pixel data is shorter than the image' };
+
+  const line = new Uint8Array(stride);
+  const previous = new Uint8Array(stride);
+  const rgba = new Uint8Array(width * height * 4);
+  const palette = header.palette;
+  const alphas = header.transparency;
+  const keyed = colorType !== 3 && alphas && alphas.length >= (colorType === 0 ? 2 : 6) ? alphas : null;
+  for (let y = 0; y < height; y += 1) {
+    const offset = y * (stride + 1);
+    const filter = raw[offset];
+    if (filter > 4) return { problem: 'a row of pixels has an unknown filter' };
+    for (let x = 0; x < stride; x += 1) {
+      const value = raw[offset + 1 + x];
+      const a = x >= bytesPerPixel ? line[x - bytesPerPixel] : 0;
+      const b = previous[x];
+      const c = x >= bytesPerPixel ? previous[x - bytesPerPixel] : 0;
+      let out = value;
+      if (filter === 1) out = value + a;
+      else if (filter === 2) out = value + b;
+      else if (filter === 3) out = value + ((a + b) >> 1);
+      else if (filter === 4) out = value + paeth(a, b, c);
+      line[x] = out & 0xff;
+    }
+    for (let x = 0; x < width; x += 1) {
+      const to = (y * width + x) * 4;
+      if (colorType === 3 || (colorType === 0 && bitDepth < 8)) {
+        const bitAt = x * bitDepth;
+        const sample = (line[bitAt >> 3] >> (8 - bitDepth - (bitAt & 7))) & ((1 << bitDepth) - 1);
+        if (colorType === 3) {
+          rgba[to] = palette ? palette[sample * 3] : 0;
+          rgba[to + 1] = palette ? palette[sample * 3 + 1] : 0;
+          rgba[to + 2] = palette ? palette[sample * 3 + 2] : 0;
+          rgba[to + 3] = alphas && sample < alphas.length ? alphas[sample] : 255;
+        } else {
+          const grey = Math.round((sample * 255) / ((1 << bitDepth) - 1));
+          rgba[to] = grey; rgba[to + 1] = grey; rgba[to + 2] = grey;
+          rgba[to + 3] = keyed && keyed.readUInt16BE(0) === sample ? 0 : 255;
+        }
+        continue;
+      }
+      // At 16 bits the high byte of each sample is what a screen shows.
+      const step = bitDepth === 16 ? 2 : 1;
+      const from = x * channels * step;
+      if (colorType === 0 || colorType === 4) {
+        const grey = line[from];
+        rgba[to] = grey; rgba[to + 1] = grey; rgba[to + 2] = grey;
+        rgba[to + 3] = colorType === 4 ? line[from + step]
+          : (keyed && (bitDepth === 16 ? (line[from] << 8) | line[from + 1] : line[from]) === keyed.readUInt16BE(0) ? 0 : 255);
+      } else {
+        rgba[to] = line[from];
+        rgba[to + 1] = line[from + step];
+        rgba[to + 2] = line[from + step * 2];
+        if (colorType === 6) rgba[to + 3] = line[from + step * 3];
+        else {
+          const sample = i => (bitDepth === 16 ? (line[from + i * 2] << 8) | line[from + i * 2 + 1] : line[from + i]);
+          rgba[to + 3] = keyed && sample(0) === keyed.readUInt16BE(0) && sample(1) === keyed.readUInt16BE(2) && sample(2) === keyed.readUInt16BE(4) ? 0 : 255;
+        }
+      }
+    }
+    previous.set(line);
+  }
+  return { width, height, rgba };
+}
+
+/** Whether a PNG can carry transparency at all, from its header. */
+export function pngHasAlphaChannel(header) {
+  return header.colorType === 4 || header.colorType === 6 || Boolean(header.transparency);
+}
+
+const WAV_FORMATS = { 1: 'pcm', 3: 'float', 6: 'a-law', 7: 'mu-law' };
+
+/**
+ * A WAV's format and length, from its `fmt ` and `data` chunks.
+ *
+ * @param {Buffer} data
+ * @returns {{codec: string, extensible: boolean, channels: number, sampleRate: number, bitsPerSample: number, durationSeconds: number|null, problem: string|null}|null} null when it is not a WAV
+ */
+export function parseWav(data) {
+  if (data.length < 12 || data.toString('latin1', 0, 4) !== 'RIFF' || data.toString('latin1', 8, 12) !== 'WAVE') return null;
+  let at = 12;
+  let format = null;
+  let dataBytes = null;
+  let problem = null;
+  while (at + 8 <= data.length) {
+    const id = data.toString('latin1', at, at + 4);
+    const length = data.readUInt32LE(at + 4);
+    const start = at + 8;
+    if (id === 'fmt ' && start + 16 <= data.length) {
+      const tag = data.readUInt16LE(start);
+      // An extensible header names the real format in the first bytes of its subformat.
+      const extended = tag === 0xfffe && start + 26 <= data.length ? data.readUInt16LE(start + 24) : null;
+      format = {
+        tag: extended ?? tag,
+        extensible: tag === 0xfffe,
+        channels: data.readUInt16LE(start + 2),
+        sampleRate: data.readUInt32LE(start + 4),
+        byteRate: data.readUInt32LE(start + 8),
+        bitsPerSample: data.readUInt16LE(start + 14)
+      };
+    } else if (id === 'data') {
+      dataBytes = length;
+      if (start + length > data.length) {
+        dataBytes = data.length - start;
+        problem = 'the sound data runs past the end of the file';
+      }
+      break;
+    }
+    at = start + length + (length & 1);
+  }
+  if (!format) return { codec: 'unknown', extensible: false, channels: 0, sampleRate: 0, bitsPerSample: 0, durationSeconds: null, problem: 'there is no format chunk' };
+  if (dataBytes === null) problem = problem || 'there is no sound data';
+  return {
+    codec: WAV_FORMATS[format.tag] || `format ${format.tag}`,
+    extensible: format.extensible,
+    channels: format.channels,
+    sampleRate: format.sampleRate,
+    bitsPerSample: format.bitsPerSample,
+    durationSeconds: dataBytes !== null && format.byteRate > 0 ? dataBytes / format.byteRate : null,
+    problem
+  };
+}
+
+/** One Ogg page: its header fields and where its body sits. */
+function oggPageAt(data, at) {
+  if (at + 27 > data.length || data.toString('latin1', at, at + 4) !== 'OggS') return null;
+  const segments = data[at + 26];
+  if (at + 27 + segments > data.length) return null;
+  let size = 0;
+  for (let i = 0; i < segments; i += 1) size += data[at + 27 + i];
+  return { granule: data.readBigInt64LE(at + 6), serial: data.readUInt32LE(at + 14), bodyStart: at + 27 + segments, next: at + 27 + segments + size };
+}
+
+/**
+ * An Ogg's codec and length: the first page names the codec, and the last page's
+ * granule position is how far the stream got. Vorbis counts samples; Opus counts
+ * at 48 kHz, less its pre-skip.
+ *
+ * @param {Buffer} data
+ * @returns {{codec: string, channels: number, sampleRate: number, bitsPerSample: null, durationSeconds: number|null, problem: string|null}|null} null when it is not an Ogg
+ */
+export function parseOgg(data) {
+  const first = oggPageAt(data, 0);
+  if (!first) return null;
+  const body = data.subarray(first.bodyStart, first.next);
+  const out = { codec: 'unknown', channels: 0, sampleRate: 0, bitsPerSample: null, durationSeconds: null, problem: null };
+  let ticksPerSecond = 0;
+  let skip = 0;
+  if (body.length >= 30 && body[0] === 1 && body.toString('latin1', 1, 7) === 'vorbis') {
+    out.codec = 'vorbis';
+    out.channels = body[11];
+    out.sampleRate = body.readUInt32LE(12);
+    ticksPerSecond = out.sampleRate;
+  } else if (body.length >= 19 && body.toString('latin1', 0, 8) === 'OpusHead') {
+    out.codec = 'opus';
+    out.channels = body[9];
+    out.sampleRate = body.readUInt32LE(12);
+    ticksPerSecond = 48000;
+    skip = body.readUInt16LE(10);
+  } else {
+    out.problem = 'the first page does not name a codec this reads';
+    return out;
+  }
+  let at = 0;
+  let lastGranule = -1n;
+  for (;;) {
+    const page = oggPageAt(data, at);
+    if (!page || page.next > data.length) break;
+    if (page.serial === first.serial && page.granule >= 0n) lastGranule = page.granule;
+    at = page.next;
+  }
+  if (at < data.length) out.problem = 'the file ends part way through a page';
+  if (lastGranule >= 0n && ticksPerSecond > 0) out.durationSeconds = Math.max(0, Number(lastGranule) - skip) / ticksPerSecond;
+  return out;
+}
+
+export default { readPngHeader, decodePng, pngHasAlphaChannel, parseWav, parseOgg, MAX_DECODED_PIXELS };