Skip to content

3D engine that AI agents drive

29.7 KB
Raw Blame
// renderer.backend "native" on render jobs: the optional hardware ray query tracer (Cook, @codepawlhq/cook) traces the scene
// the job page exported, then the job runner denoises and writes the PNG. The package and its binary are optional: when they,
// or a Vulkan ray query adapter, are missing, the job runs on the gpu or cpu backend and the report says why.
import { NOTEWORTHY_COMPILE_SECONDS } from './agent-render-estimate.mjs';
import { existsSync } from 'node:fs';
import { join, resolve } from 'node:path';
import { pathToFileURL } from 'node:url';
import { clampLimitsByEngine, requireRenderEngine } from './render-engine.mjs';
import { estimateRelativeNoise } from '../src/path-tracer-denoise.js';
import { readBlobBytes } from './cdp-blob-read.mjs';
import { applyExportDelta } from './native-export-delta.js';
import { requireExportFitsCapacity } from './native-capacity.mjs';
import { mapLookToCookPost } from './native-post-look.mjs';
import { encodeOpaquePng } from './native-png.mjs';
import { NATIVE_JOB_MAXIMUM_INSTANCES, NATIVE_JOB_MAXIMUM_TRIANGLES, chunkedTriangleBound } from './native-bake-page.js';

// The name sits in a variable so the bundler leaves the import alone; the package resolves from the user's node_modules.
const NATIVE_PACKAGE = '@codepawlhq/cook';
const INSTALL_HINT = 'npm install github:codepawl/cook, then npm run build inside it';
const MODULE_NOT_FOUND_CODES = new Set(['ERR_MODULE_NOT_FOUND', 'MODULE_NOT_FOUND']);
// The Crucible defaults of a job, lowered by the limits the installed engine declares.
const DEFAULT_ENGINE_LIMITS = { triangles: NATIVE_JOB_MAXIMUM_TRIANGLES, instances: NATIVE_JOB_MAXIMUM_INSTANCES };
const TABLE_NAMES = ['triangles', 'materials', 'lights', 'atlas', 'environmentColors', 'environmentTables', 'parameters'];
const TABLE_TYPES = { triangles: Float32Array, materials: Float32Array, lights: Float32Array, atlas: Uint32Array,
  environmentColors: Float32Array, environmentTables: Float32Array, parameters: Uint8Array };

const NOT_INSTALLED_REASON = `renderer.backend "native" needs ${NATIVE_PACKAGE} (${INSTALL_HINT}).`;

function isModuleNotFound(error, specifier) {
  return MODULE_NOT_FOUND_CODES.has(error?.code) && String(error.message).includes(specifier);
}

// COOK_PACKAGE_PATH names a local Cook checkout, whose index.mjs is imported by file URL.
function chooseSpecifier() {
  const checkoutPath = process.env.COOK_PACKAGE_PATH;
  if (!checkoutPath) return { specifier: NATIVE_PACKAGE };
  const indexPath = join(resolve(checkoutPath), 'index.mjs');
  if (!existsSync(indexPath)) return { missingReason: `renderer.backend "native" found no index.mjs in COOK_PACKAGE_PATH (${checkoutPath}); point it at a Cook checkout or unset it.` };
  return { specifier: pathToFileURL(indexPath).href };
}

// Resolves with { module }, { missingReason } for an absent package or { reason } for an install that exists but fails to load.
async function importNativePackage(importPackage) {
  const { specifier, missingReason } = chooseSpecifier();
  if (missingReason) return { missingReason };
  try {
    return { module: await importPackage(specifier) };
  } catch (error) {
    if (isModuleNotFound(error, specifier)) return { missingReason: NOT_INSTALLED_REASON };
    return { reason: `renderer.backend "native" found ${NATIVE_PACKAGE} but it failed to load (${error?.message ?? error}); reinstall it (${INSTALL_HINT}).` };
  }
}

function checkNativePackage(imported) {
  if (imported.missingReason) return { reason: imported.missingReason };
  if (imported.reason) return { reason: imported.reason };
  const checked = requireRenderEngine(imported.module);
  if (checked.reason) return { reason: `renderer.backend "native" cannot use ${NATIVE_PACKAGE}: ${checked.reason}` };
  let addonPath;
  try {
    addonPath = checked.engine.findNativeAddon();
  } catch (error) {
    return { reason: `renderer.backend "native" cannot find the binary of ${NATIVE_PACKAGE}: ${error.message}` };
  }
  if (!addonPath) return { reason: `renderer.backend "native" needs the built binary of ${NATIVE_PACKAGE} (npm run build in that package, or COOK_ADDON_PATH for a build elsewhere).` };
  // A package newer than the pinned one checks the addon's build info on load; its message (stale addon, wrong platform) is the reason as written.
  if (typeof imported.module.loadNativeAddon === 'function') {
    try {
      imported.module.loadNativeAddon();
    } catch (error) {
      return { reason: error.message };
    }
  }
  const limits = clampLimitsByEngine(DEFAULT_ENGINE_LIMITS, checked.description.limits);
  return { tracer: checked.engine, description: checked.description, limits };
}

/**
 * A cached look for the native tracer. Looking costs one import and one file check, done once per process. `markUnusable`
 * records a failure from a real trace (usually no ray query adapter), so later jobs skip the attempt and keep the reason.
 * A found tracer comes with the engine `description` and the job `limits` (Crucible defaults lowered by the engine's own).
 */
export function createNativeTracerLocator({ importPackage = specifier => import(specifier) } = {}) {
  let lookup;
  let unusableReason = null;
  return {
    async find() {
      // JS67_NATIVE_TRACER=off keeps a job on the gpu or cpu backend whatever is installed, which is also how the fallback is tested.
      if (process.env.JS67_NATIVE_TRACER === 'off') return { reason: 'renderer.backend "native" is switched off by JS67_NATIVE_TRACER=off.' };
      // COOK_DISABLE=1 behaves like an absent package (the test helper and the build honour it too).
      if (process.env.COOK_DISABLE === '1') return { reason: NOT_INSTALLED_REASON };
      lookup ??= importNativePackage(importPackage).then(checkNativePackage);
      const found = await lookup;
      if (unusableReason) return { reason: unusableReason };
      return found;
    },
    markUnusable(reason) {
      unusableReason = `renderer.backend "native" could not trace (${reason}), which usually means no Vulkan ray query adapter.`;
    },
  };
}

/**
 * Which backend a job's frames run on. "native" falls back to gpu, or to cpu on a runtime without a GPU, and `note` says why.
 * Every other request runs as asked, and the caller still rejects "gpu" on a cpu runtime.
 */
export async function chooseTraceBackend({ requested, runtimeBackend, locator }) {
  if (requested !== 'native') return { backend: requested };
  const found = await locator.find();
  if (found.tracer) return { backend: 'native', tracer: found.tracer };
  const fallback = runtimeBackend === 'cpu' ? 'cpu' : 'gpu';
  return { backend: fallback, reason: found.reason, note: `${found.reason} The ${fallback} backend ran instead.` };
}

const V2_TABLE_TYPES = { Uint8Array, Uint32Array, Int32Array, Float32Array };

// A table as bytes that start their own buffer, so any typed array can view them: base64 from a one-message export is
// decoded into a fresh buffer, and the bytes a chunked export collected are already one.
function tableBytesFrom(table) {
  if (table instanceof Uint8Array && !Buffer.isBuffer(table) && table.byteOffset === 0) return table;
  const bytes = typeof table === 'string' ? Buffer.from(table, 'base64') : table;
  const copy = new Uint8Array(bytes.length);
  copy.set(bytes);
  return copy;
}

// The manifest of a chunked export, and the capacity use of a scene that fits the adapter. A scene that cannot fit fails here,
// before any table is read from the page.
function readChunkedManifest(manifest, capacity, caller) {
  const { chunks, ...exported } = manifest;
  if (!chunks || !(chunks.chunkBytes > 0)) {
    throw new TypeError(`${caller}: the export carries no \`chunks\` manifest. Export the scene with transport "chunks".`);
  }
  return { chunks, exported, capacityUse: capacity ? requireExportFitsCapacity(manifest, capacity) : undefined };
}

/**
 * Reads every table of a chunked export (the `manifest` of splitExportForChunks) from a page that holds them as one Blob, back to
 * back in manifest order, and returns the export with its `tables` as bytes, which traceFrameNative takes like the base64 of a
 * one-message export. `readBlob(byteLength)` resolves with all of its bytes; each table is copied out into a buffer of its own.
 * No single string holds a table, so the scene is bounded by memory, not by a message. A manifest with `chunks.delta` sends only the
 * ranges that changed since the export `baseline` (`{ id, tables }`) holds; the tables come back patched, byte for byte what a full
 * export gives, and `sentBytes` says how many bytes crossed.
 */
export async function collectExportBlob(manifest, readBlob, { capacity, baseline } = {}) {
  const { chunks, exported, capacityUse } = readChunkedManifest(manifest, capacity, 'collectExportBlob');
  const { delta } = chunks;
  if (delta && baseline?.id !== delta.base) {
    throw new RangeError(`The native scene export is a delta against ${JSON.stringify(delta.base)}, and the baseline held here is ${JSON.stringify(baseline?.id)}. Export the scene again without a baseline.`);
  }
  const totalBytes = delta
    ? Object.values(delta.ranges).reduce((total, list) => total + list.reduce((sum, [, length]) => sum + length, 0), 0)
    : Object.values(chunks.tables).reduce((total, byteLength) => total + byteLength, 0);
  const blob = await readBlob(totalBytes);
  if (blob.length !== totalBytes) {
    throw new RangeError(`The native scene export sent ${blob.length} bytes, expected ${totalBytes}. The page changed the export while it was read.`);
  }
  if (delta) {
    const tables = applyExportDelta({ previous: baseline.tables, lengths: chunks.tables, ranges: delta.ranges, sent: blob });
    return { ...exported, tables, ...(capacityUse ? { capacityUse } : {}), sentBytes: totalBytes };
  }
  const tables = {};
  let offset = 0;
  for (const [name, byteLength] of Object.entries(chunks.tables)) {
    tables[name] = blob.slice(offset, offset + byteLength);
    offset += byteLength;
  }
  return { ...exported, tables, ...(capacityUse ? { capacityUse } : {}) };
}

/**
 * Exports the scene of a render job from its page and returns it with byte tables. `input` is what the page's
 * `exportNativeScene` takes. The page holds the tables as one Blob and the job runner reads it over the DevTools stream of
 * `session` (the CDP session of the page; one is made and detached here when none is passed). The page lets go of its copy
 * when the read ends, whether it succeeded or not. `capacity` (from readNativeCapacity) makes a scene the adapter cannot hold
 * fail before its tables are read. `baseline` is an object the caller keeps for the frames of one job: each frame after the first
 * reads only the table ranges that changed since the one before, unless JS67_NATIVE_EXPORT_DELTA=off. A frame that cannot use it
 * (the page lost its copy) reads every table, and the tables are the same bytes either way.
 */
export async function fetchNativeExport(page, input, { capacity, session, baseline } = {}) {
  const maximumTriangles = chunkedTriangleBound(capacity?.maxUniqueTriangles);
  const keepBaseline = baseline !== undefined && process.env.JS67_NATIVE_EXPORT_DELTA !== 'off';
  const request = { ...input, chunked: true, maximumTriangles, ...(keepBaseline ? { keepBaseline, ...(baseline.id === undefined ? {} : { deltaBase: baseline.id }) } : {}) };
  const manifest = await page.evaluate(exportRequest => window.__agentPreview.exportNativeScene(exportRequest), request);
  const { exportId } = manifest;
  const exported = await readHeldNativeExport(page, manifest, {
    blobExpression: 'window.__agentPreview.nativeExportBlob()',
    release: () => window.__agentPreview.releaseNativeExport(),
    capacity,
    session,
    baseline,
  });
  if (baseline !== undefined) {
    baseline.id = keepBaseline ? exportId : undefined;
    baseline.tables = keepBaseline && exportId !== undefined ? exported.tables : undefined;
  }
  return exported;
}

/**
 * Reads the chunked export a page holds, given the `manifest` it answered with (fetchNativeExport and the render-file CLI both
 * end here). `blobExpression` evaluates to the Blob of the tables in the page and `release` runs there when the read ends,
 * whether it succeeded or not. The Blob comes over the DevTools stream of `session` (made and detached here when none is
 * passed); `capacity` fails a scene the adapter cannot hold before any byte is read.
 */
export async function readHeldNativeExport(page, manifest, { blobExpression, release, capacity, session: givenSession, baseline }) {
  const session = givenSession ?? await page.context().newCDPSession(page);
  try {
    return await collectExportBlob(manifest, byteLength => readBlobBytes(session, blobExpression, byteLength), { capacity, baseline });
  } finally {
    await page.evaluate(release).catch(() => {});
    if (!givenSession) await session.detach().catch(() => {});
  }
}

// The FORMAT-v2 input of an instanced scene: the page names each table's array type and sends the record counts.
function decodeTablesV2(exported) {
  const input = { schemaVersion: exported.schemaVersion, ...exported.counts };
  for (const [name, base64] of Object.entries(exported.tables)) {
    const View = V2_TABLE_TYPES[exported.types?.[name]];
    if (!View) throw new TypeError(`The exported native scene table "${name}" has an unknown array type ${JSON.stringify(exported.types?.[name])}.`);
    const bytes = tableBytesFrom(base64);
    input[name] = new View(bytes.buffer, 0, bytes.length / View.BYTES_PER_ELEMENT);
  }
  return input;
}

// The bytes of every table the tracer is handed, which is what it uploads to the card (before alignment).
function tableBytes(tables) {
  return Object.values(tables).reduce((total, value) => total + (ArrayBuffer.isView(value) ? value.byteLength : 0), 0);
}

function decodeTables(exported) {
  if (exported.schemaVersion !== undefined) return decodeTablesV2(exported);
  const input = { triangleCount: exported.triangleCount };
  for (const name of TABLE_NAMES) {
    const bytes = tableBytesFrom(exported.tables[name]);
    const View = TABLE_TYPES[name];
    input[name] = new View(bytes.buffer, 0, bytes.length / View.BYTES_PER_ELEMENT);
  }
  return input;
}

function normalizeNormals(normal) {
  for (let offset = 0; offset < normal.length; offset += 3) {
    const length = Math.hypot(normal[offset], normal[offset + 1], normal[offset + 2]);
    if (length > 1e-6) {
      normal[offset] /= length;
      normal[offset + 1] /= length;
      normal[offset + 2] /= length;
    }
  }
}

function withoutAlpha(rgba, pixelCount) {
  const color = new Float32Array(pixelCount * 3);
  for (let pixel = 0; pixel < pixelCount; pixel++) {
    color.set(rgba.subarray(pixel * 4, pixel * 4 + 3), pixel * 3);
  }
  return color;
}

/**
 * The colour with every negative value raised to zero. Dispersive glass keeps signed spectral weights (as Cycles does), so a
 * trace can hold small negative pixels at the most saturated fringes. The film stays signed; this clamp sits in front of what
 * cannot take them: OIDN, and the display transforms (agx and neutral shift hue and brightness on a negative channel). The
 * wavelet and a-trous filters only average, so they keep the signs. A buffer with no negative value comes back as the same
 * array, so a render without dispersion is untouched.
 */
export function clampNegativeColor(color) {
  let clamped = null;
  for (let index = 0; index < color.length; index++) {
    if (!(color[index] < 0)) continue;
    clamped ??= color.slice();
    clamped[index] = 0;
  }
  return clamped ?? color;
}

/**
 * The native kernel a job traces with: "cycles" (the Cycles-matching kernel) unless JS67_NATIVE_KERNEL=legacy asks for the
 * older one. Any other value is passed on so `traceNative` rejects it with its own message.
 */
export function chooseNativeKernel(environment = process.env) {
  const requested = environment.JS67_NATIVE_KERNEL;
  return requested === undefined || requested === '' ? 'cycles' : requested;
}

/**
 * Whether a job keeps repeated geometry as instances: on with the "cycles" kernel, off with the legacy kernel and when
 * JS67_NATIVE_INSTANCING=off asks for flattened triangles (to compare the two, or to rule instancing out of a bug).
 */
export function chooseNativeInstancing(environment = process.env) {
  return chooseNativeKernel(environment) === 'cycles' && environment.JS67_NATIVE_INSTANCING !== 'off';
}

/**
 * The traced colour after the GPU a-trous filter, three floats per pixel. The cycles kernel already returned it when the
 * trace asked for `denoise: "atrous"`; otherwise (the legacy kernel, or the filter after OIDN failed) the tracer filters
 * the traced image with its guide buffers. Throws when the installed package cannot filter.
 */
function atrousColor({ tracer, traced, width, height }) {
  let filtered = traced.denoisedRgba;
  if (!filtered) {
    if (typeof tracer.denoiseAtrous !== 'function') throw new Error('the installed @codepawlhq/cook package has no a-trous filter');
    const { rgba, albedo, normal, depth, variance } = traced;
    filtered = tracer.denoiseAtrous({ width, height, rgba, albedo, normal, depth, variance }).rgba;
  }
  return withoutAlpha(filtered, width * height);
}

// One in-process OIDN device per loaded denoiser package, kept for the life of the process so the second and later frames
// skip device creation and the filter commit. `instance` is null when the package, the OIDN library or the addon cannot do it.
const persistentOidnByPackage = new WeakMap();

function persistentOidnFor({ tracer, denoiser }) {
  if (typeof denoiser.createOidnDenoiser !== 'function' || typeof tracer.createNativeOidnDenoiser !== 'function') return { instance: null };
  if (!persistentOidnByPackage.has(denoiser)) {
    try {
      persistentOidnByPackage.set(denoiser, { instance: denoiser.createOidnDenoiser({ createNative: tracer.createNativeOidnDenoiser }) });
    } catch (error) {
      persistentOidnByPackage.set(denoiser, { instance: null, note: error.message });
    }
  }
  return persistentOidnByPackage.get(denoiser);
}

/**
 * Runs OIDN on one frame: in the persistent in-process device when it is available, otherwise (or when that call fails)
 * through the `oidnDenoise` tool. Resolves with the filtered colour and `{ mode, note }`; `mode` is "in-process" or "cli".
 */
export async function denoiseFrameWithOidn({ tracer, denoiser, width, height, color, albedo, normal }) {
  const persistent = persistentOidnFor({ tracer, denoiser });
  let note = persistent.note;
  if (persistent.instance) {
    try {
      return { linear: await persistent.instance.denoise({ width, height, color, albedo, normal }), mode: 'in-process' };
    } catch (error) {
      note = error.message;
    }
  }
  const linear = await denoiser.denoiseWithOidn({ width, height, color, albedo, normal });
  return { linear, mode: 'cli', ...(note ? { note: `The in-process OIDN device was not used (${note}): the oidnDenoise tool ran instead.` } : {}) };
}

// Blends the filtered colour into the job's history and returns the colour to show. A frame that did not go through a
// session (a one-shot fallback) has no kernel parameter block to reproject with, so the history starts again after it.
function blendOverTime({ temporal, color, features, kernelParams, route, report }) {
  if (!kernelParams) {
    temporal.restart('the frame before did not render through a session');
    report.temporal = { historyShare: 0, restarted: 'this frame did not render through a session' };
    return color;
  }
  const started = performance.now();
  const blended = temporal.accumulate({ color, depth: features.depth, normal: features.normal, kernelParams,
    sceneChanged: route.path !== 'reused' });
  report.temporal = { historyShare: blended.historyShare, ...(blended.restarted ? { restarted: blended.restarted } : {}),
    seconds: (performance.now() - started) / 1000 };
  return blended.color;
}

/**
 * Waits one macrotask. The native addon returns each frame plane as an external ArrayBuffer whose finalizer frees the Rust
 * allocation, and V8 runs those finalizers from the event loop. A frame loop that only awaits promises never lets them
 * run, so each frame's planes pile up (about 13 MB a frame at 480 x 270) until the loop yields (codepawl/cook#34, #1211).
 */
export function yieldToEventLoop() {
  return new Promise(resolve => setImmediate(resolve));
}


/**
 * The sentence for a frame that spent seconds compiling its kernel, or undefined when it did not. Cook compiles one kernel per
 * scene variant (a scene with no emitter is a different variant from a lit one), and the first trace of a variant pays for it.
 */
export function describeKernelCompile({ compileSeconds }) {
  if (!(compileSeconds >= NOTEWORTHY_COMPILE_SECONDS)) return undefined;
  return `This frame spent ${compileSeconds.toFixed(1)} s compiling the kernel variant its scene needs, which is not trace time. Later frames of this job reuse it.`;
}

/**
 * Traces one frame the page exported and returns the PNG (base64) with the job report. `denoise` is "none", "wavelet",
 * "atrous" (the tracer's GPU filter, which is also where a missing or failing OIDN lands) or "oidn"; `denoiser` is the
 * loaded OIDN package for "oidn". The result also holds `rawLinear`, the traced colour before any filter (three floats per
 * pixel), which equals `linear` when no filter ran. `sequence` (from createNativeSequence) renders a cycles kernel frame through the job's
 * persistent session and adds `report.nativeSession`, the route the frame took. `temporal` (from createTemporalAccumulator)
 * blends the filtered colour of a session frame into the frames before it and adds `report.temporal`; `linear` is the
 * blended colour and `rawLinear` stays the traced colour of this frame alone. `viewTransform` (aces, agx or neutral), `look` and
 * `exposure` set the display look. A session frame with no JavaScript denoiser or temporal blend gets its 8-bit display bytes from
 * Cook's GPU post stage (`nativePost: false` turns that off); any other frame, or a look Cook's post cannot say, uses the
 * JavaScript helper, and `report.display` names the path and the reason. `report.encodeSeconds` is the display and PNG time. Throws when the tracer cannot run, so the caller can fall back.
 */
export async function traceFrameNative(frameOptions) {
  const traced = await traceOneFrameNative(frameOptions);
  // The frame's planes are unreferenced now, so the yield lets their finalizers run before the next frame is traced.
  await yieldToEventLoop();
  return traced;
}

/**
 * The 8-bit display bytes of a frame. Cook's GPU post stage made them (`traced.display`) when the frame asked for it and the film it
 * resolved is the film shown: no JavaScript denoiser or temporal blend changed `linear` afterwards. Otherwise the JavaScript helper
 * makes them, and `report.display` says which path ran and why.
 */
async function displayBytes({ traced, linear, width, height, nativePost, postTrace, report, look }) {
  const { toneMapToRgba8 } = await import('../src/path-tracer.js');
  if (postTrace.post && traced.display) {
    report.display = { path: 'cook-post', postSeconds: traced.postSeconds };
    return traced.display;
  }
  const reason = nativePost === false ? 'native post was switched off for this frame'
    : postTrace.reason ?? 'this frame did not render through a session';
  report.display = { path: 'javascript', reason };
  const displayed = clampNegativeColor(linear);
  const scaled = look.exposure === 1 ? displayed : displayed.map(value => value * look.exposure);
  return toneMapToRgba8(scaled, width, height, { viewTransform: look.viewTransform, look: look.look });
}

async function traceOneFrameNative({ tracer, exported, width, height, samples, bounces, seed, denoise, denoiser, maxSeconds, noiseThreshold = 0, kernel = chooseNativeKernel(), sequence, temporal,
  nativePost = true, viewTransform = 'aces', look = null, exposure = 1 }) {
  const started = performance.now();
  const filtersInTrace = denoise === 'atrous' && kernel === 'cycles';
  const tables = decodeTables(exported);
  // The GPU post stage reads the film the session resolved, so it fits only when no JavaScript step edits the film afterwards.
  const jsEditsFilm = !(denoise === 'none' || filtersInTrace) || Boolean(temporal);
  const postRequest = nativePost === false ? {} : jsEditsFilm ? { reason: 'a JavaScript denoiser or temporal blend edits the film after the trace' } : mapLookToCookPost({ viewTransform, look, exposure });
  const traceOptions = { width, height, samples, maxSeconds, kernel, noiseThreshold, ...(filtersInTrace ? { denoise: 'atrous' } : {}),
    ...(sequence && kernel === 'cycles' && postRequest.post ? { post: postRequest.post } : {}) };
  const { traced, route, kernelParams } = sequence && kernel === 'cycles'
    ? sequence.trace(tables, traceOptions)
    : { traced: tracer.traceNative(tables, traceOptions) };
  const tracedSeconds = (performance.now() - started) / 1000;
  const pixelCount = width * height;
  const features = { color: withoutAlpha(traced.rgba, pixelCount), albedo: traced.albedo, normal: traced.normal,
    depth: traced.depth, variance: traced.variance };
  normalizeNormals(features.normal);
  const averageSamples = traced.averageSamples ?? samples;
  const estimatedNoise = estimateRelativeNoise({ color: features.color, variance: features.variance, averageSamples });
  const kernelCompileNote = describeKernelCompile({ compileSeconds: traced.compileSeconds });
  const report = { width, height, samples, bounces, seed, denoised: false, denoiser: 'none', threads: 1, backend: 'native',
    gpu: traced.adapter, nativeBackend: traced.backend, nativeFeatures: traced.features, setupSeconds: traced.setupSeconds, compileSeconds: traced.compileSeconds,
    uploadSeconds: traced.uploadSeconds, accelerationBuildSeconds: traced.accelerationBuildSeconds,
    ...(traced.tracedSeconds === undefined ? {} : { gpuTraceSeconds: traced.tracedSeconds }),
    ...(kernelCompileNote ? { kernelCompileNote } : {}),
    kernel, averageSamples, noiseThreshold, ...(estimatedNoise === null ? {} : { estimatedNoise }), triangles: exported.triangles, inputBytes: tableBytes(tables), ...(exported.instances === undefined ? {} : { instances: exported.instances }),
    ...(exported.instancing === undefined ? {} : { instancing: exported.instancing, instancingReason: exported.instancingReason }),
    ...(exported.materialsReason === undefined ? {} : { materialsReason: exported.materialsReason }), tracedSeconds, ignored: exported.ignored,
    ...(route ? { nativeSession: route } : {}), ...(exported.capacityUse ? { nativeCapacity: exported.capacityUse } : {}), ...(exported.sentBytes === undefined ? {} : { exportSentBytes: exported.sentBytes }) };
  const rawLinear = features.color;
  let linear = features.color;
  const denoiseStarted = performance.now();
  if (denoise === 'oidn') {
    try {
      const filtered = await denoiseFrameWithOidn({ tracer, denoiser, width, height, color: clampNegativeColor(features.color), albedo: features.albedo, normal: features.normal });
      linear = filtered.linear;
      Object.assign(report, { denoised: true, denoiser: 'oidn', oidnVersion: denoiser.OIDN_VERSION, oidnMode: filtered.mode, ...(filtered.note ? { denoiserNote: filtered.note } : {}) });
    } catch (error) {
      report.denoiserNote = `OIDN failed (${error.message}): the GPU a-trous filter ran instead.`;
      denoise = 'atrous';
    }
  }
  if (denoise === 'atrous') {
    try {
      linear = atrousColor({ tracer, traced, width, height });
      Object.assign(report, { denoised: true, denoiser: 'atrous' });
    } catch (error) {
      const failure = `The GPU a-trous filter failed (${error.message}): the wavelet filter ran instead.`;
      report.denoiserNote = [report.denoiserNote, failure].filter(Boolean).join(' ');
      denoise = 'wavelet';
    }
  }
  if (denoise === 'wavelet') {
    const { denoiseRadiance } = await import('../src/path-tracer-denoise.js');
    linear = denoiseRadiance({ width, height, ...features });
    Object.assign(report, { denoised: true, denoiser: 'wavelet' });
  }
  if (report.denoised) report.denoiseSeconds = (performance.now() - denoiseStarted) / 1000;
  if (temporal) {
    linear = blendOverTime({ temporal, color: linear, features, kernelParams, route, report });
  }
  const encodeStarted = performance.now();
  const rgba8 = await displayBytes({ traced, linear, width, height, nativePost, postTrace: postRequest, report, look: { viewTransform, look, exposure } });
  const png = encodeOpaquePng(rgba8, width, height);
  report.encodeSeconds = (performance.now() - encodeStarted) / 1000;
  report.seconds = (performance.now() - started) / 1000;
  return { data: Buffer.from(png).toString('base64'), report, linear, rawLinear };
}

function floatsToBase64(values) {
  return Buffer.from(values.buffer, values.byteOffset, values.byteLength).toString('base64');
}

function floatsFromBase64(data) {
  const bytes = Buffer.from(data, 'base64');
  const copy = new Uint8Array(bytes.length);
  copy.set(bytes);
  return new Float32Array(copy.buffer, 0, copy.length / Float32Array.BYTES_PER_ELEMENT);
}

/**
 * Traces the texels of a recipe bake that the page packed, for the page's `__crucibleNativeBake` bridge. `request` holds the
 * scene `tables` and `triangleCount` as `exportNativeScene` makes them, plus `texelCount`, `points`, `normals` (base64
 * floats) and `samples`. Resolves with the base64 `radiance` and `escaped` arrays; throws when the tracer cannot run.
 */
export function traceTexelsNative({ tracer, request, maxSeconds }) {
  const texels = { count: request.texelCount, points: floatsFromBase64(request.points), normals: floatsFromBase64(request.normals) };
  const traced = tracer.traceNativeTexels(decodeTables(request), texels, { samples: request.samples, maxSeconds });
  return { radiance: floatsToBase64(traced.radiance), escaped: floatsToBase64(traced.escaped), adapter: traced.adapter,
    compileSeconds: traced.compileSeconds, tracedSeconds: traced.tracedSeconds };
}

/** True for the error the native tracer raises when a trace passes its `maxSeconds`: a clean failure, not a broken adapter. */
export function isNativeTimeLimitError(error) {
  if (error?.code === 'COOK_TIME_LIMIT') return true;
  return /passed its time limit/.test(error?.message ?? '');
}