@driftengine/core 3.61.0 → 3.61.2

package/scripts/cdp.mjs

@@ -0,0 +1,320 @@
+/**
+ * A Chrome DevTools Protocol client, small enough to read in one sitting.
+ *
+ * **Why this is in the engine rather than in whatever needed it this week.** A renderer cannot be
+ * judged from a unit test. Every claim this repository makes about a picture rests on
+ * photographing that picture, and every consumer of a WebGL engine has the same problem the
+ * moment it wants to know whether a change moved a pixel. This had been written from scratch
+ * three times across two repositories, with a different set of traps found the hard way in each,
+ * so it is now one thing that everybody gets.
+ *
+ * **No dependency, deliberately.** Node has had a global `WebSocket` since 21, which is the only
+ * thing a CDP client actually needs, and the engine's rule about dependencies applies to its
+ * tooling as much as to its runtime. Nothing here is imported by anything under `src/`.
+ *
+ * Pair it with `browser.mjs`, which owns launching a browser that is actually using the GPU.
+ *
+ *     import { launch } from '@driftengine/core/scripts/browser.mjs';
+ *     import { connect } from '@driftengine/core/scripts/cdp.mjs';
+ *
+ *     const browser = await launch();
+ *     const client = await connect(browser.port);
+ *     const page = await client.page('http://localhost:5173/?scene=0&hold=420', 1280, 720);
+ *     await page.settled();
+ *     await page.screenshot('before.png');
+ *     await page.close();
+ *     client.close();
+ *     await browser.close();
+ */
+import { writeFile } from 'node:fs/promises';
+
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * A phone, for `page()`'s `device` option.
+ *
+ * **A narrow `--width` is not a phone, and the difference is not cosmetic.** Real pages branch on
+ * being touch-driven in more places than they branch on being narrow, and the two are separate
+ * questions: `(pointer: coarse)` is what decides render scale, control sizes, whether a hover
+ * affordance exists at all, and — in at least one consumer — which of two entrances to a scene is
+ * built. A 390 px window driven by a mouse satisfies every `max-width` rule and none of those, so
+ * it photographs a layout no phone will ever draw and reports it as the mobile view. This preset
+ * exists so that trap is opted out of by name rather than rediscovered per consumer.
+ *
+ * Every field is overridable — `{ ...MOBILE_DEVICE, deviceScaleFactor: 3 }` — and the shape is
+ * flat rather than a device catalogue on purpose: a catalogue is a maintenance surface, and the
+ * three things that actually change a picture are the scale factor, whether touch is on, and
+ * whether the user-agent says mobile.
+ */
+export const MOBILE_DEVICE = Object.freeze({
+  mobile: true,
+  /* 2 rather than a real phone's 3: it doubles the screenshot's pixels for the same layout, and
+     the extra row of detail at 3 has never been what a capture was read for. Override for a
+     genuine text-rendering question. */
+  deviceScaleFactor: 2,
+  touch: true,
+  maxTouchPoints: 5,
+  userAgent:
+    'Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 ' +
+    '(KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1',
+  platform: 'iOS',
+  platformVersion: '17.5',
+  model: 'iPhone',
+});
+
+/** The desktop default, and the behaviour every existing caller already gets. */
+const DESKTOP_DEVICE = Object.freeze({
+  mobile: false,
+  deviceScaleFactor: 1,
+  touch: false,
+  maxTouchPoints: 0,
+  userAgent: null,
+  platform: '',
+  platformVersion: '',
+  model: '',
+});
+
+/**
+ * Open a session against a browser already listening on `port`.
+ *
+ * Returns `{ send, on, page, close }`. `send` is the raw protocol, for anything this file does
+ * not wrap; `page` is what callers normally want.
+ */
+export async function connect(port, { timeoutMs = 10_000 } = {}) {
+  const info = await (await fetch(`http://127.0.0.1:${port}/json/version`)).json();
+  const socket = new WebSocket(info.webSocketDebuggerUrl);
+  await new Promise((resolve, reject) => {
+    socket.addEventListener('open', resolve, { once: true });
+    socket.addEventListener('error', () => reject(new Error(`no CDP socket on port ${port}`)), {
+      once: true,
+    });
+  });
+
+  let nextId = 1;
+  const pending = new Map();
+  const listeners = [];
+  socket.addEventListener('message', (event) => {
+    const message = JSON.parse(event.data);
+    if (message.id !== undefined) {
+      const entry = pending.get(message.id);
+      if (entry === undefined) return;
+      pending.delete(message.id);
+      if (message.error)
+        entry.reject(new Error(`${message.method}: ${JSON.stringify(message.error)}`));
+      else entry.resolve(message.result);
+      return;
+    }
+    for (const listener of listeners) listener(message);
+  });
+
+  const send = (method, params = {}, sessionId) =>
+    new Promise((resolve, reject) => {
+      const id = nextId++;
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(new Error(`${method} did not answer within ${timeoutMs} ms`));
+      }, timeoutMs);
+      pending.set(id, {
+        resolve: (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        },
+      });
+      socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
+    });
+
+  const on = (listener) => listeners.push(listener);
+
+  /**
+   * A tab at an exact size, with its console captured from before the page loads.
+   *
+   * **The size is set twice and both are load-bearing.** `Target.createTarget` only honours
+   * `width` and `height` when `newWindow` is true, and a target left at its default can come up
+   * zero by zero — which is not an error anywhere, it is a run of
+   * `GL_INVALID_FRAMEBUFFER_OPERATION` and a black screenshot, so it reads as a renderer drawing
+   * nothing. `Emulation.setDeviceMetricsOverride` then fixes the *viewport* the page lays out
+   * against, which is a separate question from the window's own bounds.
+   *
+   * The related trap is on the page's side rather than here: a canvas sized from its layout
+   * collapses to zero if a harness hides the surrounding interface with `display: none`. Use
+   * `visibility: hidden`. Same black frame, different direction.
+   *
+   * `device` takes `MOBILE_DEVICE` (or any partial override of it) to photograph the page as a
+   * phone rather than as a narrow desktop window — see that constant for why those are not the
+   * same capture. Every override below goes on **before the first navigation**, which is the
+   * whole reason they are here rather than something a caller can do afterwards with the `call`
+   * it is handed back: `(pointer: coarse)` is read by framework state initialisers during the
+   * first render, so touch emulation switched on after load is a phone the page has already
+   * decided was a desktop.
+   */
+  const page = async (url, width = 1280, height = 720, { beforeLoad, device } = {}) => {
+    const { targetId } = await send('Target.createTarget', {
+      url: 'about:blank',
+      width,
+      height,
+      newWindow: true,
+    });
+    const { sessionId } = await send('Target.attachToTarget', { targetId, flatten: true });
+    const call = (method, params) => send(method, params, sessionId);
+    await call('Page.enable');
+    await call('Runtime.enable');
+    await call('Log.enable');
+
+    const logs = [];
+    on((message) => {
+      if (message.sessionId !== sessionId) return;
+      if (message.method === 'Log.entryAdded') {
+        logs.push(`${message.params.entry.level}: ${message.params.entry.text}`);
+      }
+      if (message.method === 'Runtime.consoleAPICalled') {
+        const text = message.params.args
+          .map((arg) => arg.value ?? arg.description ?? arg.type)
+          .join(' ');
+        logs.push(`${message.params.type}: ${text}`);
+      }
+      if (message.method === 'Runtime.exceptionThrown') {
+        const details = message.params.exceptionDetails;
+        logs.push(`exception: ${details.text} ${details.exception?.description ?? ''}`);
+      }
+    });
+
+    const metrics = { ...DESKTOP_DEVICE, ...(device ?? null) };
+
+    await call('Emulation.setDeviceMetricsOverride', {
+      width,
+      height,
+      deviceScaleFactor: metrics.deviceScaleFactor,
+      mobile: metrics.mobile,
+      /* The viewport is the layout question; `screen.width`/`screen.height` are a separate one
+         that pages read for their own reasons, and leaving them at the host monitor's size while
+         claiming to be a phone is an inconsistency worth not shipping into a capture. */
+      screenWidth: width,
+      screenHeight: height,
+      screenOrientation: metrics.mobile
+        ? {
+            type: width > height ? 'landscapePrimary' : 'portraitPrimary',
+            angle: width > height ? 90 : 0,
+          }
+        : undefined,
+    });
+
+    /*
+     * Touch and the user agent, both only when asked for. `setTouchEmulationEnabled` is what
+     * moves `(pointer: coarse)` and `(hover: none)`; the user-agent override is what moves
+     * `navigator.userAgent` and the client hints beside it. Neither implies the other, and a
+     * page can read either, so `device` sets both together rather than leaving a capture that
+     * feels like a phone to CSS and looks like a desktop to script.
+     */
+    if (metrics.touch) {
+      await call('Emulation.setTouchEmulationEnabled', {
+        enabled: true,
+        maxTouchPoints: metrics.maxTouchPoints,
+      });
+    }
+    if (metrics.userAgent !== null) {
+      await call('Emulation.setUserAgentOverride', {
+        userAgent: metrics.userAgent,
+        userAgentMetadata: {
+          brands: [],
+          fullVersion: '',
+          platform: metrics.platform,
+          platformVersion: metrics.platformVersion,
+          architecture: '',
+          model: metrics.model,
+          mobile: metrics.mobile,
+        },
+      });
+    }
+
+    /*
+     * Anything that has to run before the page's own scripts do, and this is the seam that lets
+     * the two-capture gate work against a page the harness does not own. A held clock is the case
+     * it was added for: patching `requestAnimationFrame` from here needs no cooperation from the
+     * page, so a consumer does not grow a dev-only hook on the path to production, and the
+     * same call works against a deployed build. It re-runs on every navigation within the target,
+     * which is what makes it survive a page that redirects itself.
+     */
+    if (beforeLoad !== undefined) {
+      await call('Page.addScriptToEvaluateOnNewDocument', { source: beforeLoad });
+    }
+    if (url) await call('Page.navigate', { url });
+
+    const evaluate = async (expression, options = {}) => {
+      const result = await call('Runtime.evaluate', {
+        expression,
+        awaitPromise: true,
+        returnByValue: true,
+        ...options,
+      });
+      if (result.exceptionDetails) {
+        throw new Error(
+          `${result.exceptionDetails.text} ${result.exceptionDetails.exception?.description ?? ''}`,
+        );
+      }
+      return result.result.value;
+    };
+
+    return {
+      call,
+      logs,
+      eval: evaluate,
+      /**
+       * Wait until the page says it is ready, by polling an expression *in the page*.
+       *
+       * Polling rather than a fixed sleep, because the two things worth waiting for take
+       * wildly different times: a held clock reaches its frame in a second, and a scene that
+       * streams a model can take twenty. A timeout that covers the second is dead time on
+       * every run of the first.
+       *
+       * `settleMs` is the deliberate pause *after* the condition holds, for the frames a scene
+       * draws between announcing itself and being finished.
+       */
+      async settled(expression = 'true', { timeoutMs: limit = 120_000, settleMs = 1500 } = {}) {
+        const started = Date.now();
+        for (;;) {
+          if (await evaluate(`Boolean(${expression})`)) break;
+          if (Date.now() - started > limit) throw new Error(`page never satisfied: ${expression}`);
+          await sleep(250);
+        }
+        await sleep(settleMs);
+      },
+      /**
+       * Wait `count` animation frames, which is what a picture needs rather than milliseconds.
+       *
+       * **A setting reaches a drawn pixel on the frame after the one that set it**, so anything
+       * that changes what is on screen and then photographs it has to let frames pass. A sleep is
+       * the wrong instrument for that: it is dead time when the card is quick and a race when it
+       * is not, and which one you get depends on the machine. Asked for because a consumer had
+       * written the same four lines and had got it wrong once first, which is the argument for it
+       * living here rather than in each harness.
+       */
+      async frames(count = 2) {
+        await evaluate(
+          `new Promise((resolve) => {
+             let left = ${Math.max(1, Math.floor(count))};
+             const step = () => (left-- <= 0 ? resolve(true) : requestAnimationFrame(step));
+             requestAnimationFrame(step);
+           })`,
+        );
+      },
+      /** Whatever the console holds that looks like trouble. Empty is the passing case. */
+      complaints() {
+        return logs.filter((line) => /error|exception|warning/i.test(line));
+      },
+      async screenshot(path) {
+        const shot = await call('Page.captureScreenshot', { format: 'png' });
+        await writeFile(path, Buffer.from(shot.data, 'base64'));
+        return path;
+      },
+      async close() {
+        await send('Target.closeTarget', { targetId });
+      },
+    };
+  };
+
+  return { send, on, page, close: () => socket.close() };
+}

package/scripts/frames.mjs

@@ -0,0 +1,163 @@
+/**
+ * What two frames differ by, and how speckled one is. Pure functions over decoded pixels.
+ *
+ * **These two measurements are the ones that have paid for themselves here**, and they are worth
+ * having in one place because both have a wrong version that looks right.
+ *
+ * `compare` reports by *brightness band* rather than as one number, which is what makes a result
+ * readable: "19% of the near-white pixels moved by 3, everything else by 0.03" is a description
+ * of an effect, and the single mean it collapses into is not. It was written the flat way first
+ * and the flat way could not tell a tone curve from rounding between eight bits and a half float.
+ *
+ * `speckle` counts a pixel brighter than the median of its neighbours, which is how a shading
+ * artefact made of single stray pixels gets counted at all: it survives a change of camera, it
+ * ignores a legitimate highlight's interior, and it is the metric two consumers arrived at
+ * independently while chasing the same fault.
+ */
+
+/** Rec. 709 luminance of one pixel, in 0..255. */
+export function luminance(pixels, at) {
+  return 0.2126 * pixels[at] + 0.7152 * pixels[at + 1] + 0.0722 * pixels[at + 2];
+}
+
+/** The bands `compare` splits a frame into, by the luminance of the *first* image's pixel. */
+export const BANDS = [
+  { name: 'dark', from: 0, to: 32 },
+  { name: 'mid', from: 32, to: 128 },
+  { name: 'bright', from: 128, to: 224 },
+  { name: 'near white', from: 224, to: 256 },
+];
+
+/**
+ * Two decoded images, band by band.
+ *
+ * `region` is `{ x0, y0, x1, y1 }` and defaults to the whole frame. It earns its place: a harness
+ * draws its own readout over the picture, and a frame rate printed in a corner differs between
+ * any two runs, so a comparison that includes it always reports a change.
+ *
+ * `tolerance` is the difference in luminance below which a pixel is called unchanged. 1 is the
+ * useful default, being the smallest step eight bits can express.
+ */
+export function compare(one, two, { region, tolerance = 1 } = {}) {
+  if (one.width !== two.width || one.height !== two.height) {
+    throw new Error(
+      `frames are ${one.width}x${one.height} and ${two.width}x${two.height}; nothing to compare`,
+    );
+  }
+  const box = {
+    x0: region?.x0 ?? 0,
+    y0: region?.y0 ?? 0,
+    x1: region?.x1 ?? one.width,
+    y1: region?.y1 ?? one.height,
+  };
+  const bands = BANDS.map((band) => ({ ...band, pixels: 0, changed: 0, delta: 0 }));
+
+  let pixels = 0;
+  let changed = 0;
+  let delta = 0;
+  let worst = 0;
+  let worstAt = null;
+  let sumOne = 0;
+  let sumTwo = 0;
+
+  for (let y = box.y0; y < box.y1; y++) {
+    for (let x = box.x0; x < box.x1; x++) {
+      const at = (y * one.width + x) * one.channels;
+      const a = luminance(one.pixels, at);
+      const b = luminance(two.pixels, at);
+      const d = Math.abs(a - b);
+      pixels++;
+      sumOne += a;
+      sumTwo += b;
+      const band =
+        bands.find((entry) => a >= entry.from && a < entry.to) ?? bands[bands.length - 1];
+      band.pixels++;
+      if (d > tolerance) {
+        changed++;
+        delta += d;
+        band.changed++;
+        band.delta += d;
+        if (d > worst) {
+          worst = d;
+          worstAt = { x, y };
+        }
+      }
+    }
+  }
+
+  const mean = (sum, count) => (count === 0 ? 0 : sum / count);
+  return {
+    pixels,
+    changed,
+    meanDelta: mean(delta, changed),
+    worst,
+    worstAt,
+    meanLuminance: [mean(sumOne, pixels), mean(sumTwo, pixels)],
+    bands: bands.map((band) => ({
+      name: band.name,
+      pixels: band.pixels,
+      changed: band.changed,
+      meanDelta: mean(band.delta, band.changed),
+    })),
+  };
+}
+
+/**
+ * How many pixels stand brighter than the median of their eight neighbours by more than
+ * `threshold`.
+ *
+ * The 3x3 median rather than the mean, and this is the part that matters: a mean is dragged up by
+ * the very pixel being tested, so a bright speck partly hides itself and a run of them reads as a
+ * gentle gradient. A median ignores it entirely, so the comparison is against what the
+ * neighbourhood would have been.
+ *
+ * Two thresholds are usually worth reporting together. The lower one moves with legitimate
+ * silhouette detail and the higher one is the artefact, so a change that improves one and not the
+ * other has said something specific.
+ */
+export function speckle(image, { threshold = 12, region } = {}) {
+  const box = {
+    x0: Math.max(1, region?.x0 ?? 1),
+    y0: Math.max(1, region?.y0 ?? 1),
+    x1: Math.min(image.width - 1, region?.x1 ?? image.width - 1),
+    y1: Math.min(image.height - 1, region?.y1 ?? image.height - 1),
+  };
+  const neighbours = new Array(9);
+  let count = 0;
+  for (let y = box.y0; y < box.y1; y++) {
+    for (let x = box.x0; x < box.x1; x++) {
+      let n = 0;
+      for (let dy = -1; dy <= 1; dy++) {
+        for (let dx = -1; dx <= 1; dx++) {
+          neighbours[n++] = luminance(
+            image.pixels,
+            ((y + dy) * image.width + (x + dx)) * image.channels,
+          );
+        }
+      }
+      const centre = neighbours[4];
+      const sorted = neighbours.slice().sort((a, b) => a - b);
+      if (centre - sorted[4] > threshold) count++;
+    }
+  }
+  return count;
+}
+
+/** One line per band, for printing a `compare` result without every caller writing the format. */
+export function formatComparison(result) {
+  const lines = [
+    `${result.changed} of ${result.pixels} pixels changed, mean delta ${result.meanDelta.toFixed(2)}`,
+    `mean luminance ${result.meanLuminance[0].toFixed(1)} to ${result.meanLuminance[1].toFixed(1)}` +
+      (result.worstAt === null
+        ? ''
+        : `, worst ${result.worst.toFixed(0)} at ${result.worstAt.x},${result.worstAt.y}`),
+  ];
+  for (const band of result.bands) {
+    const share = band.pixels === 0 ? 0 : (band.changed / band.pixels) * 100;
+    lines.push(
+      `  ${band.name.padEnd(11)}${String(band.pixels).padStart(9)} px ` +
+        `${share.toFixed(1).padStart(6)}% changed, mean delta ${band.meanDelta.toFixed(2)}`,
+    );
+  }
+  return lines.join('\n');
+}

package/scripts/heldClock.mjs

@@ -0,0 +1,98 @@
+/**
+ * A held clock, as a script to inject into a page the harness does not own.
+ *
+ * **Why this exists next to `demo/dev/heldFrame.ts` rather than instead of it.** Two runs of one
+ * build differ in zero pixels only if the frame being photographed is the same frame, and a
+ * scene's state is a function of elapsed time: a load that stalls a few frames puts the camera
+ * somewhere else. Measured while chasing a shading artefact, two captures taken at the same
+ * wall-clock offset from one page differed in **736,190 pixels of 921,600**.
+ *
+ * The engine's own harness takes `?hold=N` and freezes itself, which is right for a person typing
+ * a URL: they get a badge saying the clock has stopped, and a frame rate read off a held page is
+ * otherwise a lie. **A consumer has no such hook and should not have to grow one.** Adding
+ * a dev-only clock patch to a game's entry point puts harness code on the path to production and
+ * makes the gate something each consumer implements. Injected before the page's own scripts run,
+ * it needs no cooperation at all and works against a deployed build as readily as a dev server.
+ *
+ * So the two exist for different callers and the duplication is the price: this one is injected
+ * from outside and stays silent, that one is asked for from inside and announces itself. If the
+ * stepping ever changes, change both, and the fixed 1/60 below is the engine's own step rather
+ * than a number chosen here.
+ */
+
+/** What a frame is worth, matching the engine's fixed simulation step. */
+const STEP_MS = 1000 / 60;
+
+/**
+ * Source for `beforeLoad`, freezing the page after exactly `frames` steps.
+ *
+ * The shape is the same as the in-page version and each part of it is load-bearing. Callbacks are
+ * queued rather than called through, because a scene that re-requests inside its own callback
+ * would recurse to the stack limit. The pump is a task rather than a microtask, so fetch, worker
+ * and decode callbacks get their turn: without that, a page that streams a model holds at zero
+ * parts for ever and photographs an empty stage.
+ */
+export function heldClockScript(frames, { startWhen = 'true' } = {}) {
+  const wanted = Math.max(1, Math.floor(frames));
+  return `(() => {
+  const realRaf = window.requestAnimationFrame.bind(window);
+  const realNow = performance.now.bind(performance);
+  let virtualMs = 0;
+  let advanced = 0;
+  let taken = false;
+  let pending = [];
+
+  /*
+   * Nothing is taken over until the page says it is ready, and that is the part that makes this
+   * work on a game rather than only on a scene that mounts synchronously.
+   *
+   * Measured on one: holding from page load left two runs of one build differing in 12,023 pixels
+   * of 921,600, because the clock advances a frame per turn of the task queue whether or not the
+   * load has finished, so the number of frames the game had actually drawn by frame N depended on
+   * when a worker and an audio decode happened to resolve. Counting from a stated state instead
+   * makes the frame that gets photographed the same frame.
+   */
+  const ready = () => { try { return Boolean(${startWhen}); } catch (error) { return false; } };
+
+  const take = () => {
+    taken = true;
+    /* Continue from the real clock rather than from zero: a page that has already read the time
+       and stored an origin would otherwise see it run backwards. */
+    virtualMs = realNow();
+    performance.now = () => virtualMs;
+    window.requestAnimationFrame = (callback) => { pending.push(callback); return pending.length; };
+    window.cancelAnimationFrame = () => {};
+    const pump = () => {
+      const due = pending;
+      pending = [];
+      /*
+       * The clock moves for a frame that is actually drawn, and not for a turn of the task queue
+       * that happens to find nothing waiting.
+       *
+       * Measured on a game whose load is asynchronous: advancing per turn left two runs of one
+       * build differing in 895 pixels, because the turns that elapse while a worker and an audio
+       * decode resolve are real turns and there are a different number of them each time. Tying
+       * the step to a callback makes the page see exactly N frames of 1/60 however long its load
+       * took. The cost is that a page which stops asking for frames stops the clock, which is
+       * correct here and is why a caller states what to wait for.
+       */
+      if (due.length > 0 && advanced < ${wanted}) { virtualMs += ${STEP_MS}; advanced++; }
+      for (const callback of due) callback(virtualMs);
+      /* A task rather than a microtask, so fetch, worker and decode callbacks get their turn. */
+      setTimeout(pump, 0);
+    };
+    setTimeout(pump, 0);
+  };
+
+  const watch = () => {
+    if (ready()) take();
+    else realRaf(watch);
+  };
+  realRaf(watch);
+
+  /* What a caller waits on, since there is no badge to look for when nobody is looking. */
+  Object.defineProperty(window, '__heldFrame', {
+    get: () => (taken && advanced >= ${wanted} ? advanced : 0),
+  });
+})();`;
+}

package/scripts/mesh-bench.ts

@@ -0,0 +1,71 @@
+/**
+ * What `MeshBuilder.build()` costs, and what it used to.
+ *
+ * **A benchmark rather than a test**, in `island-bench.ts`'s shape: nothing here asserts, because a
+ * wall-clock number on one machine is evidence and not a contract. `npm run bench:mesh`.
+ *
+ * **Why the number matters to somebody other than this repository.** A consumer streaming a world
+ * builds its geometry between frames, and `build()` was one uninterruptible call: measured at
+ * 41.9 ms here for 110,628 triangles, two and a half frames at 16.7 ms. That is what made them cap
+ * a batch at a triangle count tuned to one laptop — 32,000, which is seven milliseconds there and
+ * unknown on a phone — and overshoot it by whatever the last object was, up to 47,040 against a cap
+ * of 32,000, because a batch is told what went into it after it went in.
+ *
+ * Two things fixed it and both are visible below: the builder writes into growable typed arrays as
+ * geometry arrives, so `build()` is a slice rather than ten conversions of boxed doubles; and the
+ * five "did anything differ from the default" questions it asked by scanning every vertex are now
+ * answered by a flag the write sets. **41.9 ms to 1.6 ms.**
+ *
+ * `triangleCount` is printed beside them because it is the other half of the same report: a caller
+ * can now ask how big a builder has become instead of tallying it, which is what lets a cap be
+ * honest rather than approximate.
+ */
+import { MeshBuilder } from '../src/geometry/meshBuilder';
+
+/** The consumer's own figure for one region's street-plate lettering, at twelve triangles a box. */
+const TRIANGLES = 110628;
+const BOXES = Math.round(TRIANGLES / 12);
+const RUNS = 7;
+
+function fill(): MeshBuilder {
+  const builder = new MeshBuilder();
+  for (let i = 0; i < BOXES; i++) {
+    builder.addBox(i * 0.01, 0, (i % 37) * 0.01, 0.004, 0.004, 0.001, [0.9, 0.9, 0.9]);
+  }
+  return builder;
+}
+
+const median = (values: number[]): number =>
+  values.slice().sort((a, b) => a - b)[Math.floor(values.length / 2)] as number;
+
+/* Warm up: the first run of anything in a fresh isolate measures the compiler. */
+for (let i = 0; i < 2; i++) fill().build();
+
+const fills: number[] = [];
+const builds: number[] = [];
+let triangles = 0;
+let vertices = 0;
+for (let run = 0; run < RUNS; run++) {
+  let started = performance.now();
+  const builder = fill();
+  fills.push(performance.now() - started);
+
+  /* Asked before building, which is the point of it: no mesh exists yet. */
+  triangles = builder.triangleCount;
+  vertices = builder.vertexCountSoFar;
+
+  started = performance.now();
+  const mesh = builder.build();
+  builds.push(performance.now() - started);
+  if (mesh.indices.length / 3 !== triangles) {
+    throw new Error(
+      `triangleCount said ${triangles} and build() produced ${mesh.indices.length / 3}. ` +
+        'Those are the same question and a caller batching by size is trusting the first one.',
+    );
+  }
+}
+
+console.log(`\n  ${triangles} triangles, ${vertices} vertices, median of ${RUNS}`);
+console.log(`    fill    ${median(fills).toFixed(1)} ms   the caller's own loop`);
+console.log(`    build   ${median(builds).toFixed(1)} ms   the stop, against 41.9 ms before`);
+console.log(`    total   ${(median(fills) + median(builds)).toFixed(1)} ms\n`);

package/scripts/png.d.mts

@@ -0,0 +1,17 @@
+/** What a decoded PNG is: row-major 8-bit samples, three or four to a pixel. */
+export interface DecodedPng {
+  readonly width: number;
+  readonly height: number;
+  readonly channels: number;
+  readonly pixels: Buffer;
+}
+
+export function decodePng(bytes: Buffer): DecodedPng;
+export function readPng(path: string): DecodedPng;
+
+/**
+ * Write 8-bit RGBA as a PNG. `rgba` must be exactly `width * height * 4` bytes.
+ *
+ * Node-side only — `node:zlib` is the whole of it, and nothing a browser loads links this.
+ */
+export function encodePng(width: number, height: number, rgba: Buffer | Uint8Array): Buffer;