@instruktlabs/kiln 0.0.0-stage → 1.0.0

package/src/views/capture-cache.ts

@@ -0,0 +1,272 @@
+import { createHash } from 'node:crypto';
+import {
+  validatePbrRenderRequest,
+  type PbrRenderPort,
+  type PbrRenderResult,
+  type PbrRenderRequest,
+} from '../composer/render-port';
+import type { GlbViewCellResult } from './index';
+import type { ResolvedAssetCameraV1 } from './camera';
+import { decodePng } from './png';
+import { enforcePngCaptureBudget } from './capture-limits';
+export type CaptureCacheEntry =
+  | { kind: 'gpu'; result: PbrRenderResult }
+  | { kind: 'cpu'; result: GlbViewCellResult };
+export interface CaptureCache {
+  get(key: string): Promise<CaptureCacheEntry | undefined>;
+  put(key: string, value: CaptureCacheEntry): Promise<void>;
+}
+function clone(entry: CaptureCacheEntry): CaptureCacheEntry {
+  const result = structuredClone(entry);
+  if (result.kind === 'cpu') result.result.png = Buffer.from(result.result.png);
+  return result;
+}
+/** One host-owned byte budget for disposable cells. Entries retain the producer and evidence. */
+export class MemoryCaptureCache implements CaptureCache {
+  private readonly entries = new Map<string, { entry: CaptureCacheEntry; bytes: number }>();
+  private bytes = 0;
+  constructor(private readonly maxBytes = 64 * 1024 * 1024) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
+      throw new Error('Capture cache bytes must be a nonnegative integer');
+  }
+  async get(key: string) {
+    const value = this.entries.get(key);
+    if (!value) return undefined;
+    this.entries.delete(key);
+    this.entries.set(key, value);
+    return clone(value.entry);
+  }
+  async put(key: string, value: CaptureCacheEntry) {
+    const entry = clone(value);
+    let bytes: number;
+    if (entry.kind === 'gpu') {
+      const { viewsPng, beautyPng, ...metadata } = entry.result;
+      bytes =
+        (viewsPng ?? []).reduce((sum, png) => sum + png.byteLength, 0) +
+        (beautyPng?.byteLength ?? 0) +
+        Buffer.byteLength(JSON.stringify(metadata));
+    } else {
+      const { png, ...metadata } = entry.result;
+      bytes = png.byteLength + Buffer.byteLength(JSON.stringify(metadata));
+    }
+    if (bytes > this.maxBytes) return;
+    const old = this.entries.get(key);
+    if (old) {
+      this.bytes -= old.bytes;
+      this.entries.delete(key);
+    }
+    while (this.bytes + bytes > this.maxBytes) {
+      const first = this.entries.keys().next().value;
+      if (first === undefined) break;
+      this.bytes -= this.entries.get(first)!.bytes;
+      this.entries.delete(first);
+    }
+    this.entries.set(key, { entry, bytes });
+    this.bytes += bytes;
+  }
+  stats() {
+    return { entries: this.entries.size, bytes: this.bytes, maxBytes: this.maxBytes };
+  }
+}
+function canonical(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === 'object')
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([k, v]) => [k, canonical(v)]),
+    );
+  if (typeof value === 'number' && !Number.isFinite(value))
+    throw new Error('Non-finite capture identity');
+  if (
+    value === undefined ||
+    value === null ||
+    ['string', 'number', 'boolean'].includes(typeof value)
+  )
+    return value;
+  throw new Error('Capture identity must be data');
+}
+const text = (value: unknown) => JSON.stringify(canonical(value));
+const digest = (value: string | Uint8Array) =>
+  `sha256:${createHash('sha256').update(value).digest('hex')}` as const;
+function usable(result: PbrRenderResult, request: PbrRenderRequest, hash: string): boolean {
+  try {
+    if (
+      !result.ok ||
+      !result.rendererId?.trim() ||
+      result.derivativeFidelity?.materialFaithful !== true ||
+      result.derivativeFidelity.inputGlbSha256 !== hash
+    )
+      return false;
+    const count = (request.cameras ?? request.viewDirs)!.length;
+    if (result.viewsPng?.length !== count) return false;
+    if (
+      request.cameras &&
+      (result.width !== request.width ||
+        result.height !== request.height ||
+        text(result.cameras) !== text(request.cameras))
+    )
+      return false;
+    enforcePngCaptureBudget(result.viewsPng);
+    for (const png of result.viewsPng) {
+      const image = decodePng(png);
+      if (
+        image.width !== image.height ||
+        (request.cameras && (image.width !== request.width || image.height !== request.height))
+      )
+        return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+/** Cache only acknowledged material-faithful GPU cells. Identity must include backend/version and hidden render settings. */
+export function createCachedRenderPort(
+  port: PbrRenderPort,
+  options: { cache: CaptureCache; identity(): string | undefined | Promise<string | undefined> },
+): PbrRenderPort {
+  return async (input, execution) => {
+    execution?.signal?.throwIfAborted();
+    const identity = await Promise.resolve()
+      .then(() => options.identity())
+      .catch(() => undefined);
+    execution?.signal?.throwIfAborted();
+    if (!identity || input.beautySize !== undefined || !(input.cameras ?? input.viewDirs)?.length)
+      return port(input, execution);
+    const validated = validatePbrRenderRequest(input);
+    const request = { ...validated, glb: Uint8Array.from(validated.glb) };
+    const hash = digest(request.glb);
+    const selectors = request.cameras ?? request.viewDirs!;
+    const keys = selectors.map((selector) =>
+      digest(
+        text({
+          version: 'kiln.capture-cache.v1',
+          kind: 'gpu',
+          identity,
+          artifact: hash,
+          selector,
+          size: request.size,
+          width: request.width,
+          height: request.height,
+          lighting: request.lightingPresetId,
+          backdrop: request.backdrop,
+        }),
+      ),
+    );
+    const cells: Array<PbrRenderResult | undefined> = [];
+    const missing: number[] = [];
+    for (let i = 0; i < keys.length; i++) {
+      const cached = await options.cache.get(keys[i]!).catch(() => undefined);
+      execution?.signal?.throwIfAborted();
+      const single = {
+        ...request,
+        ...(request.cameras
+          ? { cameras: [request.cameras[i]!] }
+          : { viewDirs: [request.viewDirs![i]!] }),
+      };
+      if (cached?.kind === 'gpu' && usable(cached.result, single, hash)) cells[i] = cached.result;
+      else missing.push(i);
+    }
+    if (missing.length) {
+      const subrequest = {
+        ...request,
+        ...(request.cameras
+          ? { cameras: missing.map((i) => request.cameras![i]!) }
+          : { viewDirs: missing.map((i) => request.viewDirs![i]!) }),
+      };
+      const produced = await port(subrequest, execution);
+      execution?.signal?.throwIfAborted();
+      const afterIdentity = await Promise.resolve()
+        .then(() => options.identity())
+        .catch(() => undefined);
+      execution?.signal?.throwIfAborted();
+      if (afterIdentity !== identity)
+        return missing.length === selectors.length
+          ? produced
+          : {
+              ok: false,
+              rendererId: produced.rendererId,
+              error: 'capture producer changed during render',
+            };
+      if (!usable(produced, subrequest, hash)) {
+        // Returning a partial batch as a successful full sheet would mislabel images.
+        return missing.length === selectors.length
+          ? produced
+          : {
+              ok: false,
+              rendererId: produced.rendererId,
+              error: produced.error ?? 'uncacheable partial camera response',
+            };
+      }
+      for (let j = 0; j < missing.length; j++) {
+        const i = missing[j]!;
+        const cell = {
+          ...produced,
+          viewsPng: [Uint8Array.from(produced.viewsPng![j]!)],
+          ...(produced.cameras ? { cameras: [produced.cameras[j]!] } : {}),
+        };
+        cells[i] = cell;
+        await options.cache.put(keys[i]!, { kind: 'gpu', result: cell }).catch(() => {});
+      }
+    }
+    const first = cells[0]!;
+    if (cells.some((c) => c!.rendererId !== first.rendererId))
+      return {
+        ok: false,
+        rendererId: first.rendererId,
+        error: 'capture producer changed; refresh host cache identity',
+      };
+    return {
+      ...first,
+      viewsPng: cells.map((c) => Uint8Array.from(c!.viewsPng![0]!)),
+      ...(request.cameras ? { cameras: structuredClone(request.cameras) } : {}),
+      captureCache: {
+        hit: missing.length === 0,
+        reused: selectors.length - missing.length,
+        total: selectors.length,
+      },
+    };
+  };
+}
+export interface CpuCaptureIdentity {
+  artifactGlbSha256: `sha256:${string}`;
+  rendererId: string;
+  camera: ResolvedAssetCameraV1;
+  size: number;
+  backfaceCull?: boolean;
+  /** Painted backdrop; part of the key because the pixels differ per backdrop. */
+  backdrop?: import('./background').BackdropId;
+}
+/** CPU entries are explicitly geometry-flat and live in a different key namespace from GPU cells. */
+export async function captureCpuCell(
+  cache: CaptureCache,
+  identity: CpuCaptureIdentity,
+  produce: () => Promise<GlbViewCellResult>,
+): Promise<GlbViewCellResult & { captureCache?: { hit: boolean } }> {
+  const snapshot = structuredClone(identity);
+  const key = digest(text({ version: 'kiln.capture-cache.v1', kind: 'cpu', ...snapshot }));
+  const valid = (result: GlbViewCellResult) => {
+    try {
+      enforcePngCaptureBudget([result.png]);
+      const image = decodePng(result.png);
+      return (
+        result.inputGlbSha256 === snapshot.artifactGlbSha256 &&
+        image.width === snapshot.size &&
+        image.height === snapshot.size &&
+        result.width === snapshot.size &&
+        result.height === snapshot.size
+      );
+    } catch {
+      return false;
+    }
+  };
+  const cached = await cache.get(key).catch(() => undefined);
+  if (cached?.kind === 'cpu' && valid(cached.result))
+    return { ...cached.result, png: Buffer.from(cached.result.png), captureCache: { hit: true } };
+  const result = await produce();
+  if (!valid(result)) return result;
+  await cache.put(key, { kind: 'cpu', result }).catch(() => {});
+  return { ...result, png: Buffer.from(result.png), captureCache: { hit: false } };
+}

package/src/views/capture-limits.ts

@@ -0,0 +1,73 @@
+import { PAD } from './grid';
+export interface CaptureLimits {
+  maxTotalPixels?: number;
+  maxOutputBytes?: number;
+}
+/**
+ * Largest square per-shot size for kiln.capture.v1. The render service accepts
+ * camera-mode images up to 4096 px a side and 16.7M pixels per request, and 2048
+ * is its top legacy rung; the capture pixel and byte budgets below bound the sheet.
+ */
+export const MAX_CAPTURE_SHOT_SIZE = 2048;
+export const DEFAULT_CAPTURE_LIMITS = Object.freeze({
+  maxTotalPixels: 24_000_000,
+  maxOutputBytes: 32 * 1024 * 1024,
+});
+export function resolveCaptureLimits(limits: CaptureLimits = {}) {
+  const result: Required<CaptureLimits> = { ...DEFAULT_CAPTURE_LIMITS };
+  for (const key of ['maxTotalPixels', 'maxOutputBytes'] as const) {
+    const value = limits[key];
+    if (value !== undefined) {
+      if (!Number.isSafeInteger(value) || value < 1)
+        throw new Error(`capture limit ${key} must be a positive integer`);
+      result[key] = Math.min(value, result[key]);
+    }
+  }
+  return result;
+}
+export function enforceCapturePixels(
+  cells: number,
+  size: number,
+  cols: number,
+  limits?: CaptureLimits,
+  compose = true,
+) {
+  if (
+    !Number.isSafeInteger(cells) ||
+    cells < 1 ||
+    !Number.isSafeInteger(size) ||
+    size < 1 ||
+    !Number.isSafeInteger(cols) ||
+    cols < 1
+  )
+    throw new Error('invalid capture dimensions');
+  const pixels =
+    cells * size * size +
+    (compose
+      ? (cols * size + (cols + 1) * PAD) *
+        (Math.ceil(cells / cols) * size + (Math.ceil(cells / cols) + 1) * PAD)
+      : 0);
+  if (pixels > resolveCaptureLimits(limits).maxTotalPixels)
+    throw new Error(`capture pixel budget exceeded: ${pixels}`);
+  return pixels;
+}
+export function enforceCaptureBytes(images: readonly Uint8Array[], limits?: CaptureLimits) {
+  const bytes = images.reduce((sum, image) => sum + image.byteLength, 0);
+  if (bytes > resolveCaptureLimits(limits).maxOutputBytes)
+    throw new Error(`capture byte budget exceeded: ${bytes}`);
+  return bytes;
+}
+/** Bound declared raster dimensions before a decoder allocates inflated pixel storage. */
+export function enforcePngCaptureBudget(images: readonly Uint8Array[], limits?: CaptureLimits) {
+  enforceCaptureBytes(images, limits);
+  let pixels = 0;
+  for (const png of images) {
+    if (png.byteLength < 24) throw new Error('invalid PNG header');
+    const view = new DataView(png.buffer, png.byteOffset, png.byteLength);
+    if (view.getUint32(0) !== 0x89504e47 || view.getUint32(12) !== 0x49484452)
+      throw new Error('invalid PNG header');
+    pixels += view.getUint32(16) * view.getUint32(20);
+  }
+  if (pixels > resolveCaptureLimits(limits).maxTotalPixels)
+    throw new Error(`capture pixel budget exceeded: ${pixels}`);
+}

package/src/views/capture.ts

@@ -0,0 +1,300 @@
+/**
+ * Capture configuration for the view grid (T3.2).
+ *
+ * The contact sheet was a fixed 3x2 of six named cameras. That is the right
+ * default and stays the default, but it is wrong often enough to matter: a
+ * symmetric prop wastes four cells restating the same silhouette, and a
+ * complex asset with an occluded interior needs angles the six do not include.
+ * This module lets the model choose the grid shape and, if it wants, every
+ * cell's camera.
+ *
+ * ## The one hard rule
+ *
+ * Omitting `capture` must reproduce the existing 3x2 output **byte for byte**.
+ * Every default here is arranged around that: {@link DEFAULT_CAPTURE_PRESET} is
+ * `3x2`, its cells are `SIX_VIEWS` by identity (not a copy that could drift),
+ * and per-cell `zoom` is only applied when explicitly supplied, because passing
+ * frame bounds at all changes the framing path away from per-cell auto-framing.
+ *
+ * ## Preset naming
+ *
+ * `COLSxROWS`, matching how the existing grid is described throughout the
+ * codebase ("6 cells @ 3 cols = 3x2"). So `3x1` is a wide strip and `1x2` is a
+ * tall pair.
+ */
+
+import { SIX_VIEWS, type ViewSpec, orbitAnglesOf, orbitDir, resolveGridViews } from './raster';
+import { BACKDROP_IDS, DEFAULT_BACKDROP_ID, isBackdropId, type BackdropId } from './background';
+
+/** Grid shapes the model may ask for. `COLS x ROWS`. */
+export type CapturePreset = '1x1' | '1x2' | '2x1' | '3x1' | '2x2' | '3x2' | '3x3';
+
+export const CAPTURE_PRESETS: readonly CapturePreset[] = [
+  '1x1',
+  '1x2',
+  '2x1',
+  '3x1',
+  '2x2',
+  '3x2',
+  '3x3',
+] as const;
+
+/** The shipped contact sheet. Omitting `capture` resolves to exactly this. */
+export const DEFAULT_CAPTURE_PRESET: CapturePreset = '3x2';
+
+/** Hard cap on cells, so a runaway config cannot blow up render time or tokens. */
+export const MAX_CAPTURE_CELLS = 9;
+
+/** One model-specified camera. Angles are object-relative, same frame as `kiln_inspect`. */
+export interface CaptureCell {
+  azimuthDeg: number;
+  elevationDeg: number;
+  /** Padding multiplier around the asset bounds. Omit for the default auto-framing. */
+  zoom?: number;
+  /** Optional cell label. Auto-derived from the angles when omitted. */
+  name?: string;
+}
+
+export interface CaptureConfig {
+  version?: 'kiln.capture.v1' | 'kiln.capture.v2';
+  shots?: import('./camera').CameraShotV1[];
+  cols?: number;
+  size?: number;
+  output?: 'grid' | 'separate';
+  preset?: CapturePreset;
+  cells?: CaptureCell[];
+  /**
+   * Named backdrop behind every cell. Omit for the default. One of three fixed
+   * colours rather than a free hex, so sheets stay comparable across runs and a
+   * backdrop can never be tuned to hide a seam. See `views/background.ts`.
+   */
+  backdrop?: BackdropId;
+}
+
+/** Columns for each preset. Rows follow from the cell count. */
+const PRESET_COLS: Record<CapturePreset, number> = {
+  '1x1': 1,
+  '1x2': 1,
+  '2x1': 2,
+  '3x1': 3,
+  '2x2': 2,
+  '3x2': 3,
+  '3x3': 3,
+};
+
+/** Cell capacity of each preset. */
+const PRESET_CAPACITY: Record<CapturePreset, number> = {
+  '1x1': 1,
+  '1x2': 2,
+  '2x1': 2,
+  '3x1': 3,
+  '2x2': 4,
+  '3x2': 6,
+  '3x3': 9,
+};
+
+/** Two extra cameras the six-view set has no room for. */
+const BOTTOM: ViewSpec = { name: 'BOTTOM', dir: [0, -1, 0.0001] };
+const THREE_QUARTER_REAR: ViewSpec = { name: 'REAR 34', dir: [-0.7, 0.5, -0.7] };
+const THREE_QUARTER_LOW: ViewSpec = { name: 'LOW 34', dir: [0.7, -0.35, 0.7] };
+
+/**
+ * Default cameras per preset, chosen so a smaller grid drops the least
+ * informative cells rather than simply truncating the six in order.
+ *
+ * A single cell is the 3/4, not the front: one orthographic elevation reads as
+ * a flat rectangle for most assets, while the quarter view carries depth,
+ * proportion and silhouette at once. Two cells add the front for a readable
+ * measurement reference. `3x2` is `SIX_VIEWS` itself — same array identity, so
+ * a future edit to the six-view set cannot silently desynchronise the default.
+ */
+const PRESET_VIEWS: Record<CapturePreset, ViewSpec[]> = {
+  '1x1': [SIX_VIEWS[5]!],
+  '1x2': [SIX_VIEWS[0]!, SIX_VIEWS[5]!],
+  '2x1': [SIX_VIEWS[0]!, SIX_VIEWS[5]!],
+  '3x1': [SIX_VIEWS[0]!, SIX_VIEWS[1]!, SIX_VIEWS[5]!],
+  '2x2': [SIX_VIEWS[0]!, SIX_VIEWS[1]!, SIX_VIEWS[4]!, SIX_VIEWS[5]!],
+  '3x2': SIX_VIEWS,
+  '3x3': [...SIX_VIEWS, BOTTOM, THREE_QUARTER_REAR, THREE_QUARTER_LOW],
+};
+
+/**
+ * Label an orbit cell using only glyphs the 3x5 bitmap font actually has
+ * (uppercase, digits, space — there is no minus sign, so elevation sign is
+ * carried by U/D rather than a `-` that would render as a blank box).
+ */
+export function captureCellLabel(azimuthDeg: number, elevationDeg: number): string {
+  const az = Math.round(((azimuthDeg % 360) + 360) % 360);
+  const el = Math.round(elevationDeg);
+  return `A${az} ${el < 0 ? 'D' : 'U'}${Math.abs(el)}`;
+}
+
+export interface ResolvedCapture {
+  preset: CapturePreset;
+  views: ViewSpec[];
+  cols: number;
+  /** Per-cell zoom, aligned with `views`. `undefined` means auto-frame. */
+  zooms: Array<number | undefined>;
+  /** True when the result is the untouched shipped default. */
+  isDefault: boolean;
+  /** The backdrop every cell is painted on. */
+  backdrop: BackdropId;
+}
+
+/**
+ * The layout a contact sheet was actually produced in, reported alongside it.
+ *
+ * Shared by the tool result, the `views` artifact and the render port so a
+ * consumer never has to infer the grid shape by dividing image dimensions.
+ */
+export interface CaptureShape {
+  preset: string;
+  cols: number;
+  cells: number;
+  /** Echoed so the model never has to guess what colour it is looking at. */
+  backdrop?: BackdropId;
+  /**
+   * Delivery of a versioned capture: one sheet (`grid`, laid out as `preset`)
+   * or one image per shot (`separate`). Absent for the default six-view sheet.
+   */
+  output?: 'grid' | 'separate';
+}
+
+export class CaptureConfigError extends Error {}
+
+/** Validate an optional backdrop id, naming the choices on a miss. */
+export function resolveCaptureBackdrop(backdrop: unknown): BackdropId {
+  if (backdrop === undefined) return DEFAULT_BACKDROP_ID;
+  if (!isBackdropId(backdrop))
+    throw new CaptureConfigError(
+      `capture.backdrop must be one of ${BACKDROP_IDS.join(', ')} (got ${JSON.stringify(backdrop)}).`,
+    );
+  return backdrop;
+}
+
+/**
+ * Resolve a capture config into the view list, column count and per-cell zooms
+ * the grid renderer needs.
+ *
+ * Throws {@link CaptureConfigError} on anything the model got wrong, with a
+ * message naming the fix — these come back through the tool result, so they are
+ * the model's only feedback channel.
+ */
+export function resolveCapture(config?: CaptureConfig): ResolvedCapture {
+  const backdrop = resolveCaptureBackdrop(config?.backdrop);
+  if (!config || (config.preset === undefined && config.cells === undefined)) {
+    return {
+      preset: DEFAULT_CAPTURE_PRESET,
+      views: PRESET_VIEWS[DEFAULT_CAPTURE_PRESET],
+      cols: PRESET_COLS[DEFAULT_CAPTURE_PRESET],
+      zooms: new Array(PRESET_CAPACITY[DEFAULT_CAPTURE_PRESET]).fill(undefined),
+      isDefault: true,
+      backdrop,
+    };
+  }
+
+  const cells = config.cells;
+  let preset = config.preset;
+
+  if (preset !== undefined && !CAPTURE_PRESETS.includes(preset)) {
+    throw new CaptureConfigError(
+      `capture.preset must be one of ${CAPTURE_PRESETS.join(', ')} (got ${JSON.stringify(preset)}).`,
+    );
+  }
+
+  if (cells !== undefined) {
+    if (!Array.isArray(cells) || cells.length === 0) {
+      throw new CaptureConfigError('capture.cells must be a non-empty array of camera angles.');
+    }
+    if (cells.length > MAX_CAPTURE_CELLS) {
+      throw new CaptureConfigError(
+        `capture.cells has ${cells.length} entries; the maximum is ${MAX_CAPTURE_CELLS}.`,
+      );
+    }
+    for (let i = 0; i < cells.length; i++) {
+      const c = cells[i]!;
+      if (!Number.isFinite(c?.azimuthDeg) || !Number.isFinite(c?.elevationDeg)) {
+        throw new CaptureConfigError(
+          `capture.cells[${i}] needs finite azimuthDeg and elevationDeg (got ${JSON.stringify(c)}).`,
+        );
+      }
+      if (c.zoom !== undefined && (!Number.isFinite(c.zoom) || c.zoom <= 0)) {
+        throw new CaptureConfigError(
+          `capture.cells[${i}].zoom must be a positive number (got ${c.zoom}).`,
+        );
+      }
+    }
+
+    // Pick the tightest preset that fits when none was named, so `cells` alone
+    // is a complete request rather than an error about a missing preset.
+    if (preset === undefined) {
+      preset = CAPTURE_PRESETS.find((p) => PRESET_CAPACITY[p] >= cells.length)!;
+    } else if (cells.length > PRESET_CAPACITY[preset]) {
+      throw new CaptureConfigError(
+        `capture.preset ${preset} holds ${PRESET_CAPACITY[preset]} cells but ${cells.length} were given. ` +
+          `Use a larger preset or fewer cells.`,
+      );
+    }
+
+    return {
+      preset,
+      views: cells.map((c) => ({
+        name: c.name?.trim().toUpperCase() || captureCellLabel(c.azimuthDeg, c.elevationDeg),
+        dir: orbitDir(c.azimuthDeg, c.elevationDeg),
+      })),
+      cols: PRESET_COLS[preset],
+      zooms: cells.map((c) => c.zoom),
+      isDefault: false,
+      backdrop,
+    };
+  }
+
+  // Preset only: use its default cameras.
+  const chosen = preset!;
+  return {
+    preset: chosen,
+    views: PRESET_VIEWS[chosen],
+    cols: PRESET_COLS[chosen],
+    zooms: new Array(PRESET_VIEWS[chosen].length).fill(undefined),
+    isDefault: chosen === DEFAULT_CAPTURE_PRESET,
+    backdrop,
+  };
+}
+
+/**
+ * Resolve a capture config the way every grid producer must (T3.3).
+ *
+ * There are two producers of the same contact sheet — the CPU rasterizer and the
+ * GPU render port — and they have to agree on the layout down to the cell order,
+ * or a run's artifact silently changes shape depending on whether a GPU happened
+ * to be reachable. This is the one function both call, so the precedence rule
+ * exists once:
+ *
+ *   capture supplied  -> exactly what it asks for
+ *   capture omitted   -> the `KILN_GRID_VARIANT` view set at the shipped 3 cols
+ *
+ * The env variant only applies to the omitted case on purpose: it swaps the
+ * *default* six cameras for a bench arm, and silently rewriting a caller's
+ * explicitly-requested angles would make the request a lie.
+ */
+export function resolveGridCapture(config?: CaptureConfig, envVariant?: string): ResolvedCapture {
+  const resolved = resolveCapture(config);
+  if (config) return resolved;
+  const views = resolveGridViews(envVariant);
+  // Identity when the variant is unset/unknown, so the default stays the exact
+  // object the byte-identity tests pin.
+  return views === resolved.views ? resolved : { ...resolved, views };
+}
+
+/** Describe a resolved capture for the tool result, in the model's own coordinates. */
+export function describeCapture(resolved: ResolvedCapture): string {
+  const angles = resolved.views
+    .map((v) => {
+      const { azimuthDeg, elevationDeg } = orbitAnglesOf(v.dir);
+      return `${v.name} (az ${azimuthDeg}, el ${elevationDeg})`;
+    })
+    .join('; ');
+  return `${resolved.preset} grid, ${resolved.views.length} cell${
+    resolved.views.length === 1 ? '' : 's'
+  }: ${angles}`;
+}