Skip to content

armgit / kiln

Public Imported from GitHub
0

Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.

37.5 KB
Raw Blame
import { enforceCapturePixels, enforceCaptureBytes, type CaptureLimits } from './capture-limits';
import { DEFAULT_BACKDROP_ID } from './background';
export { DEFAULT_CAPTURE_LIMITS, resolveCaptureLimits } from './capture-limits';
export type { CaptureLimits } from './capture-limits';
import { captureCpuCell, type CaptureCache } from './capture-cache';
export * from './capture-cache';
import {
  rasterizeCamera,
  rasterizeCameraPaced,
  cameraFromBounds,
  resolveAssetCamera,
  selectCameraSubject,
  withCameraVisibility,
  type CameraShotV1,
  type ResolvedCameraShotV1,
  type ResolvedAssetCameraV1,
} from './camera';
import { renderCaptureGrid } from './camera-capture';
export * from './camera';
export * from './camera-capture';
/**
 * Six-view grid rendering for the Kiln vision loop.
 *
 * Renders a scene (or a Kiln program) to a 3x2 grid PNG of orthographic
 * views — Front / Right / Back / Left | Top / 3-4 — using the pure-CPU
 * rasterizer in ./raster.ts. This is what the agent sees via the
 * kiln_screenshot tool and what ships as the views.png artifact.
 *
 * Grid order (H-30: now ALSO stamped into each cell as a label + axis gnomon,
 * matching the animation/interior grids — grid-confusion literature shows
 * text-only layout descriptions silently fail):
 *   row 1: Front, Right, Back
 *   row 2: Left,  Top,   3/4
 */

import {
  rasterizeView,
  measureBounds,
  measurePartBounds,
  hideNodeInScene,
  type RasterOptions,
  type ViewSpec,
} from './raster';
import { encodePng } from './png';
import { decodePngShared } from './png-memo';
import { compositeCellGrid } from './grid';
import { annotateViewCell } from './annotate';
import { resolveGridCapture, type CaptureConfig, type CaptureShape } from './capture';
import {
  prepareClip,
  measureLoopClosure,
  poseSceneAtTime,
  planFrameTimes,
  findClip,
  clipNames,
  stampLabel,
  type DuckClip,
} from './pose';
import { hideArchitectureRoofInScene } from './architecture';
import {
  buildSlotIndex,
  chooseSlot,
  hexToLinearRgb,
  type SnapPaletteSlot,
  type Vec3,
} from '../palette-snap';
import {
  loadGlbGeometryFlatScene,
  loadGlbReviewScene,
  type GlbGeometryFlatReasonCode,
} from './glb';
import {
  resolveEvaluatorPortV2,
  type EvaluatorExecutionProfileV2,
  type EvaluatorPortV2,
} from '../evaluator';

export {
  rasterizeView,
  measureBounds,
  hideNodeInScene,
  SIX_VIEWS,
  SIX_VIEWS_REAR_QUARTER,
  resolveGridViews,
  coverage,
  orbitDir,
  orbitAnglesOf,
  MIN_ELEVATION_DEG,
  MAX_ELEVATION_DEG,
} from './raster';
export type { RasterOptions, ViewSpec, ViewGridVariant } from './raster';
export { annotateViewCell, stampAxisGnomon } from './annotate';
export {
  BACKDROPS,
  BACKDROP_IDS,
  DEFAULT_BACKDROP_ID,
  GRID_BACKGROUND_HEX,
  GRID_BACKGROUND_RGB,
  isBackdropId,
  resolveBackdrop,
} from './background';
export type { Backdrop, BackdropId } from './background';
export { encodePng, decodePng } from './png';
export type { DecodedPng } from './png';
export {
  CAPTURE_PRESETS,
  CaptureConfigError,
  DEFAULT_CAPTURE_PRESET,
  MAX_CAPTURE_CELLS,
  captureCellLabel,
  describeCapture,
  resolveCapture,
  resolveGridCapture,
} from './capture';
export type {
  CaptureCell,
  CaptureConfig,
  CapturePreset,
  CaptureShape,
  ResolvedCapture,
} from './capture';
export { compositeCellGrid, compositeViewPngGrid, GRID_COLS } from './grid';
export { ViewEvidenceHistoryStore } from './evidence-history';
export type { ComposedCellGrid, ComposedPngGrid } from './grid';
export { CPU_RASTER_RENDERER_ID } from './renderer-id';
export {
  GLB_GEOMETRY_FLAT_REASON,
  GlbGeometryFlatError,
  geometryFlatTextureReasonCode,
  loadGlbGeometryFlatScene,
  loadGlbReviewScene,
} from './glb';
export type {
  GlbGeometryFlatErrorCode,
  GlbGeometryFlatReasonCode,
  GlbGeometryFlatRoot,
  LoadedGlbGeometryFlatScene,
  LoadedGlbReviewScene,
} from './glb';
export {
  ARCHITECTURE_ROOF_ROLE_PREFIXES,
  hasArchitectureRoofRole,
  hideArchitectureRoofInScene,
  selectArchitectureRoofNodes,
} from './architecture';
export type {
  ArchitectureRoofSelection,
  ArchitectureRoofSelectionMode,
  ArchitectureViewNode,
} from './architecture';
export { rasterizeComposedScene, SCENE_VIEWS } from './scene-raster';
export type { ComposedPart, ComposedSceneRasterResult } from './scene-raster';
export {
  GENERIC_DIAGNOSTIC_BUFFER_IDS,
  GENERIC_DIAGNOSTIC_CAMERAS,
  GENERIC_DIAGNOSTIC_REQUESTS,
  planDiagnosticViews,
  renderDiagnosticView,
  renderDiagnosticViews,
} from './diagnostic';
export {
  CHARACTER_MOTION_DIAGNOSTIC_PHASES,
  buildCharacterDiagnosticDescriptor,
  planCharacterDiagnosticRequests,
} from './character';
export type {
  CharacterDiagnosticDescriptorV1,
  CharacterDiagnosticEdgeV1,
  CharacterDiagnosticJointV1,
  CharacterDiagnosticRequestV1,
} from './character';
export {
  captureVehicleDiagnosticViews,
  createVehicleDiagnosticOverlay,
  describeVehicleDiagnostics,
} from './vehicle';
export type {
  VehicleCapturedDiagnosticV1,
  VehicleDiagnosticAxleV1,
  VehicleDiagnosticDescriptorV1,
  VehicleDiagnosticViewV1,
  VehicleDiagnosticWheelV1,
} from './vehicle';
export type {
  CategoryDiagnosticVariant,
  DiagnosticCameraSpec,
  DiagnosticOverlayRegion,
  DiagnosticRenderOptions,
  DiagnosticViewFrame,
  DiagnosticViewPlanV1,
  DiagnosticViewRequest,
  GenericDiagnosticBufferId,
} from './diagnostic';
export {
  prepareClip,
  poseSceneAtTime,
  planFrameTimes,
  findClip,
  clipNames,
  type DuckClip,
  type PreparedClip,
} from './pose';

interface DuckColor {
  r: number;
  g: number;
  b: number;
}

interface DuckMaterial {
  color?: DuckColor;
  emissive?: DuckColor;
  emissiveIntensity?: number;
  transparent?: boolean;
  opacity?: number;
  metalness?: number;
  roughness?: number;
  map?: unknown;
  vertexColors?: boolean;
}

interface DuckMesh {
  isMesh?: boolean;
  material?: DuckMaterial | DuckMaterial[];
}

interface DuckObject3D {
  traverse?: (cb: (obj: DuckMesh) => void) => void;
}

export interface ScenePaletteSnapResult {
  snapped: number;
  skipped: number;
}

function setLinearColor(color: DuckColor | undefined, rgb: Vec3): void {
  if (!color) return;
  color.r = rgb[0];
  color.g = rgb[1];
  color.b = rgb[2];
}

function snapMaterialToPalette(
  mat: DuckMaterial,
  slots: readonly SnapPaletteSlot[],
  idx: ReturnType<typeof buildSlotIndex>,
): boolean | undefined {
  if (!mat.color) return undefined;
  if (mat.map || mat.vertexColors) return false;

  const emissive =
    mat.emissive && (mat.emissiveIntensity ?? 1) > 0
      ? ([
          mat.emissive.r * (mat.emissiveIntensity ?? 1),
          mat.emissive.g * (mat.emissiveIntensity ?? 1),
          mat.emissive.b * (mat.emissiveIntensity ?? 1),
        ] as Vec3)
      : undefined;
  const slotI = chooseSlot(idx, {
    baseLinear: [mat.color.r, mat.color.g, mat.color.b],
    ...(emissive ? { emissiveLinear: emissive } : {}),
    transparent: mat.transparent === true || (mat.opacity !== undefined && mat.opacity < 0.98),
  });
  if (slotI === undefined) return false;

  const slot = slots[slotI]!;
  const kind = slot.kind ?? 'opaque';
  const rgb = hexToLinearRgb(slot.color);
  setLinearColor(mat.color, rgb);
  if (mat.metalness !== undefined) mat.metalness = slot.metalness ?? 0;
  if (mat.roughness !== undefined)
    mat.roughness = slot.roughness ?? (kind === 'glass' ? 0.1 : 0.85);

  if (kind === 'glass') {
    mat.transparent = true;
    mat.opacity = slot.opacity ?? 0.4;
  } else {
    if (mat.transparent !== undefined) mat.transparent = false;
    if (mat.opacity !== undefined) mat.opacity = 1;
  }

  if (mat.emissive) {
    if (kind === 'glow') {
      setLinearColor(mat.emissive, rgb);
      mat.emissiveIntensity = Math.max(mat.emissiveIntensity ?? 1, 1);
    } else {
      setLinearColor(mat.emissive, [0, 0, 0]);
      if (mat.emissiveIntensity !== undefined) mat.emissiveIntensity = 0;
    }
  }
  return true;
}

/** Snap flat-color scene materials to a palette before CPU preview rasterization. */
export function snapSceneToPalette(
  root: unknown,
  slots: readonly SnapPaletteSlot[],
): ScenePaletteSnapResult {
  if (slots.length === 0) return { snapped: 0, skipped: 0 };
  const traverse = (root as DuckObject3D | undefined)?.traverse;
  if (!traverse) return { snapped: 0, skipped: 0 };

  const idx = buildSlotIndex(slots);
  let snapped = 0;
  let skipped = 0;
  traverse.call(root, (obj: DuckMesh) => {
    if (!obj.isMesh || !obj.material) return;
    const materials = Array.isArray(obj.material) ? obj.material : [obj.material];
    for (const mat of materials) {
      const didSnap = snapMaterialToPalette(mat, slots, idx);
      if (didSnap === true) snapped++;
      else if (didSnap === false) skipped++;
    }
  });
  return { snapped, skipped };
}

export interface ViewGridResult {
  captureCache?: { hit: boolean; reused: number; total: number };
  /** Resolved identities and cameras for versioned capture shots. */
  cameraShots?: ResolvedCameraShotV1[];
  png: Buffer;
  width: number;
  height: number;
  /** View names in grid order (row-major). */
  views: string[];
  /** Grid shape actually rendered by the model-facing contact sheet — the
   *  default reports `3x2`. Absent on the fixed diagnostic layouts (interior
   *  cutaway, animation strip), which have their own row shape and would have
   *  to invent a preset name to report one. */
  capture?: CaptureShape;
}

export interface ViewGridOptions extends RasterOptions {
  captureLimits?: CaptureLimits;
  captureCache?: CaptureCache;
  /** Exact GLB identity, supplied automatically by renderGlbViewGrid. */
  artifactGlbSha256?: `sha256:${string}`;
  views?: ViewSpec[];
  /** Snap flat-color materials before rasterization. Mutates the provided scene root. */
  snapPalette?: readonly SnapPaletteSlot[];
  /** Model-chosen grid shape and cameras. Omit for the shipped 3x2 contact sheet.
   *  Ignored when `views` is passed explicitly (internal callers win). */
  capture?: CaptureConfig;
  /** Column count override. Defaults to the capture preset's columns. */
  cols?: number;
}

/** Render a (possibly sandbox-created) Three.js scene root into the 3x2 grid. */
export async function renderViewGrid(
  root: unknown,
  opts: ViewGridOptions = {},
): Promise<ViewGridResult> {
  // H-31: 384px cells (was 256). Measured input-image cost of the full grid:
  // Anthropic ~w*h/750 tokens => 1168x780 ≈ 1,215 tok (vs 784x524 ≈ 548) —
  // negligible against 32-64K reasoning budgets; 512 would double it again for
  // marginal legibility gain at typical asset scales. Candidate thumbnails
  // downscale separately (Studio thumbnailFor), unaffected.
  if (opts.capture?.shots || opts.capture?.version)
    return renderCaptureGrid(root, opts.capture, undefined, opts.captureLimits);
  const size = opts.size ?? 384;
  // H-33: the default view set is env-selectable (KILN_GRID_VARIANT=rear-quarter
  // swaps the 3/4 cell to the opposite-rear azimuth) so a bench arm can flip the
  // grid per-process without any wire or tool-schema change. Explicit opts.views
  // always wins; unset/unknown env keeps SIX_VIEWS.
  //
  // T3.2: `capture` lets the model pick the grid shape and per-cell cameras.
  // The env variant and an explicit `views` both still win, in that order of
  // specificity, so no internal caller changes behavior. With `capture`
  // omitted this resolves to SIX_VIEWS at 3 columns — the previous constants.
  const resolved = resolveGridCapture(opts.capture, process.env['KILN_GRID_VARIANT']);
  const views = opts.views ?? resolved.views;
  const cols = opts.cols ?? resolved.cols;
  enforceCapturePixels(views.length, size, cols, opts.captureLimits);
  if (opts.snapPalette?.length) snapSceneToPalette(root, opts.snapPalette);

  // Per-cell zoom needs a shared frame box; measuring is only worth it when a
  // zoom was actually requested. Passing frameBounds unconditionally would
  // route every render through a different framing path than before and break
  // the byte-identity guarantee for the default grid.
  const wantsZoom = resolved.zooms.some((z) => z !== undefined);
  const sceneBounds = wantsZoom ? measureBounds(root) : undefined;
  // An explicit raster option wins over the capture's backdrop, matching how
  // `views`/`cols` already treat internal callers; both default to neutral.
  const backdrop = opts.backdrop ?? resolved.backdrop;

  const cache = opts.snapPalette?.length ? undefined : opts.captureCache;
  let reused = 0;
  const cells: Uint8Array[] = [];
  for (let vi = 0; vi < views.length; vi++) {
    const zoom = resolved.zooms[vi];
    const rasterOptions = {
      size,
      backfaceCull: opts.backfaceCull,
      backdrop,
      ...(opts.frameBounds ? { frameBounds: opts.frameBounds } : {}),
      ...(sceneBounds && zoom !== undefined
        ? { frameBounds: expandFrameBounds(sceneBounds, zoom) }
        : {}),
    };
    let cell: Uint8Array;
    if (cache && opts.artifactGlbSha256) {
      const { CPU_RASTER_RENDERER_ID } = await import('./renderer-id');
      const camera = cameraFromBounds(
        rasterOptions.frameBounds ?? measureBounds(root),
        views[vi]!.dir,
      );
      const result = await captureCpuCell(
        cache,
        {
          artifactGlbSha256: opts.artifactGlbSha256,
          rendererId: `${CPU_RASTER_RENDERER_ID}/legacy-fit`,
          camera,
          size,
          backfaceCull: opts.backfaceCull ?? true,
          backdrop,
        },
        async () => ({
          png: encodePng(rasterizeView(root, views[vi]!.dir, rasterOptions), size, size),
          width: size,
          height: size,
          inputGlbSha256: opts.artifactGlbSha256!,
          reasonCodes: [],
          meshCount: 0,
          instanceCount: 0,
        }),
      );
      if (result.captureCache?.hit) reused++;
      cell = decodePngShared(result.png).rgb;
    } else cell = rasterizeView(root, views[vi]!.dir, rasterOptions);
    // H-30: view name + axis gnomon, via the annotator the GPU port shares.
    annotateViewCell(cell, size, views[vi]!);
    cells.push(cell);
  }
  const { rgb, width, height } = compositeCellGrid(cells, size, cols);

  const png = encodePng(rgb, width, height);
  enforceCaptureBytes([png], opts.captureLimits);
  return {
    png,
    width,
    height,
    views: views.map((v) => v.name),
    capture: { preset: resolved.preset, cols, cells: views.length, backdrop },
    ...(cache && opts.artifactGlbSha256
      ? { captureCache: { hit: reused === views.length, reused, total: views.length } }
      : {}),
  };
}

export interface GlbViewGridResult extends ViewGridResult {
  /** Identity of the exact byte array parsed for this fallback. */
  inputGlbSha256: `sha256:${string}`;
  /** Stable limitations of geometry-flat rendering for this artifact. */
  reasonCodes: GlbGeometryFlatReasonCode[];
  meshCount: number;
  instanceCount: number;
}

async function hashGlbViewInput(bytes: Uint8Array): Promise<`sha256:${string}`> {
  const copy = Uint8Array.from(bytes);
  const digest = new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', copy));
  return `sha256:${[...digest].map((value) => value.toString(16).padStart(2, '0')).join('')}`;
}

export interface GlbViewCellResult {
  png: Buffer;
  width: number;
  height: number;
  inputGlbSha256: `sha256:${string}`;
  reasonCodes: GlbGeometryFlatReasonCode[];
  meshCount: number;
  instanceCount: number;
}

/** Render one unannotated geometry-flat cell from an immutable GLB snapshot. */
export async function renderGlbViewCell(
  bytes: Uint8Array,
  view: ViewSpec,
  options: RasterOptions & {
    camera?: ResolvedAssetCameraV1;
    /** The call's cancellation, honoured at the rasterizer's pauses. */
    execution?: { signal?: AbortSignal };
  } = {},
): Promise<GlbViewCellResult> {
  const exactBytes = Uint8Array.from(bytes);
  const loaded = await loadGlbGeometryFlatScene(exactBytes);
  const size = options.size ?? 256;
  const rgb = options.camera
    ? await rasterizeCameraPaced(
        loaded.root,
        options.camera,
        size,
        options.backfaceCull,
        options.backdrop,
        options.execution?.signal,
      )
    : rasterizeView(loaded.root, view.dir, {
        size,
        ...(options.backdrop ? { backdrop: options.backdrop } : {}),
        ...(options.backfaceCull !== undefined ? { backfaceCull: options.backfaceCull } : {}),
        ...(options.frameBounds ? { frameBounds: options.frameBounds } : {}),
      });
  return {
    png: encodePng(rgb, size, size),
    width: size,
    height: size,
    inputGlbSha256: await hashGlbViewInput(exactBytes),
    reasonCodes: loaded.reasonCodes,
    meshCount: loaded.meshCount,
    instanceCount: loaded.instanceCount,
  };
}

/** Render the geometry-flat contact sheet from exact final GLB bytes. */
export async function renderGlbViewGrid(
  bytes: Uint8Array,
  options: ViewGridOptions = {},
): Promise<GlbViewGridResult> {
  // One immutable snapshot owns both parsing and identity. Even a caller that
  // mutates its Buffer while this async render is running cannot make the
  // rasterized geometry and reported hash refer to different byte sequences.
  const exactBytes = Uint8Array.from(bytes);
  // Exact subject paths and LOD chains need the hierarchy; the legacy flat adapter
  // deliberately has neither names nor children. Both loaders read these exact bytes.
  const loaded =
    options.capture?.version || options.capture?.shots
      ? await loadGlbReviewScene(exactBytes)
      : await loadGlbGeometryFlatScene(exactBytes);
  const artifactGlbSha256 = await hashGlbViewInput(exactBytes);
  const grid = await renderViewGrid(loaded.root, { ...options, artifactGlbSha256 });
  return {
    ...grid,
    inputGlbSha256: await hashGlbViewInput(exactBytes),
    reasonCodes: loaded.reasonCodes,
    meshCount: loaded.meshCount,
    instanceCount: loaded.instanceCount,
  };
}

/** Grow a bounds box about its center — the per-cell `zoom` padding. */
function expandFrameBounds(
  b: { min: [number, number, number]; max: [number, number, number] },
  factor: number,
): { min: [number, number, number]; max: [number, number, number] } {
  const min: [number, number, number] = [0, 0, 0];
  const max: [number, number, number] = [0, 0, 0];
  for (let a = 0; a < 3; a++) {
    const center = (b.min[a]! + b.max[a]!) / 2;
    const half = ((b.max[a]! - b.min[a]!) / 2) * factor;
    min[a] = center - half;
    max[a] = center + half;
  }
  return { min, max };
}

/** Execute a Kiln program and render its scene into the 3x2 grid. */
export interface CodeViewGridOptions extends ViewGridOptions {
  evaluatorPort?: EvaluatorPortV2;
  evaluatorProfile?: EvaluatorExecutionProfileV2;
}

export async function renderCodeViewGrid(
  code: string,
  opts: CodeViewGridOptions = {},
): Promise<ViewGridResult> {
  const { evaluatorPort, evaluatorProfile, ...viewOptions } = opts;
  const rendered = await resolveEvaluatorPortV2(
    evaluatorPort,
    evaluatorProfile ?? 'trusted-local',
  ).render(code);
  return renderGlbViewGrid(rendered.glb, viewOptions);
}

// =============================================================================
// Animation views — see one clip's MOTION (kiln_screenshot_animation)
// =============================================================================

/** Friendly camera names → orthographic view directions (kiln frame). The default
 *  is RIGHT: the side profile reveals forward/back leg swing, knee bend direction,
 *  and the arc of an attack — the motion defects a static grid can't show. */
const ANIM_CAMERAS: Record<string, ViewSpec> = {
  front: { name: 'Front', dir: [1, 0, 0] },
  right: { name: 'Right', dir: [0, 0, 1] },
  back: { name: 'Back', dir: [-1, 0, 0] },
  left: { name: 'Left', dir: [0, 0, -1] },
  top: { name: 'Top', dir: [0, 1, 0.0001] },
  'three-quarter': { name: '3/4', dir: [0.7, 0.5, 0.7] },
};
const ANIM_CAMERA_ALIASES: Record<string, string> = {
  '3/4': 'three-quarter',
  '34': 'three-quarter',
  threequarter: 'three-quarter',
  quarter: 'three-quarter',
  perspective: 'three-quarter',
  side: 'right',
  profile: 'right',
};

function resolveCamera(name?: string): ViewSpec {
  const key = (name ?? 'right')
    .trim()
    .toLowerCase()
    .replace(/[_\s]+/g, '-');
  return (
    ANIM_CAMERAS[key] ?? ANIM_CAMERAS[ANIM_CAMERA_ALIASES[key] ?? ''] ?? ANIM_CAMERAS['right']!
  );
}

export interface AnimationViewOptions extends RasterOptions {
  shot?: CameraShotV1;
  /** Up to 16 exact subtrees to measure at every pose, independent of the camera. */
  measureParts?: NonNullable<CameraShotV1['subject']>[];
  frameTimes?: number[];
  framing?: 'locked' | 'follow';
  /** Clip to render, by name (case-insensitive, substring-tolerant). Omit → first clip. */
  clip?: string;
  /** Camera angle. Default 'right' (side profile). */
  camera?: string;
  /** Frames sampled across the clip (start→end inclusive). Default 6. */
  frames?: number;
  /** Return the frames as separate PNGs instead of one composite grid. Default false. */
  perFrame?: boolean;
  /** Internal derivative renderer. Receives the already-posed scene and must
   * render exactly one square cell without executing generated source. */
  renderDerivativeCell?: DerivativeCellRenderer;
}

export interface DerivativeCellRenderInput {
  camera?: ResolvedAssetCameraV1;
  root: unknown;
  label: string;
  view: ViewSpec;
  size: number;
  backfaceCull?: boolean;
  frameBounds?: { min: [number, number, number]; max: [number, number, number] };
  /** Backdrop the cell must be painted on, by either producer. */
  backdrop?: import('./background').BackdropId;
  /** Stable reason to decline GPU when its auto-framing cannot honor this view. */
  gpuUnsupportedReasonCode?: 'DERIVATIVE_GPU_FRAMING_UNSUPPORTED';
}

export interface DerivativeCellRenderResult {
  png: Buffer;
  receipt: import('../composer/render-port').DerivativeViewReceiptV1;
}

export type DerivativeCellRenderer = (
  input: DerivativeCellRenderInput,
) => Promise<DerivativeCellRenderResult>;

/** Drawable geometry in world metres before camera isolation/cutaway. Samples
 * describe only the requested poses, not swept bounds or collision/contact QA. */
export interface AnimationPoseBounds {
  phase: number;
  timeSeconds: number;
  scene: { min: [number, number, number]; max: [number, number, number] };
  /** Selected shot subject, if any, in the same world coordinate system. */
  subject?: { min: [number, number, number]; max: [number, number, number] };
  /**
   * Input order; null bounds mean no drawable triangles, never inferred contact.
   * origin is the node's world position, so a locator without geometry is still measured.
   */
  parts?: {
    path: string;
    name: string;
    bounds: ReturnType<typeof measurePartBounds>;
    origin: [number, number, number];
  }[];
}

function worldOrigin(node: unknown): [number, number, number] {
  const e = (node as { matrixWorld: { elements: ArrayLike<number> } }).matrixWorld.elements;
  return [e[12]!, e[13]!, e[14]!];
}

/** Distance from a point to an axis-aligned box; zero inside it. */
function boxDistance(
  point: readonly number[],
  box: { min: readonly number[]; max: readonly number[] },
): number {
  let sum = 0;
  for (let a = 0; a < 3; a++) {
    const d = Math.max(box.min[a]! - point[a]!, 0, point[a]! - box.max[a]!);
    sum += d * d;
  }
  return Math.sqrt(sum);
}

export interface AnimationViewResult {
  loopClosure?: import('./pose').LoopClosureEvidence;
  cameraShots?: ResolvedCameraShotV1[];
  ok: boolean;
  clip?: string;
  camera?: string;
  frames: number;
  /** Phase fraction (0..1) of each frame, in order. */
  frameTimes: number[];
  poseBounds?: AnimationPoseBounds[];
  /** Clip duration in seconds. */
  duration?: number;
  /** Track targets that resolve to no joint — the "frozen clip" signal (cause #1). */
  unresolvedTracks?: string[];
  width?: number;
  height?: number;
  /** Composite grid PNG (default mode). */
  png?: Buffer;
  /** Per-frame PNGs (perFrame mode). */
  pngs?: Buffer[];
  /** Clip names available in the scene (set on a not-found error). */
  availableClips?: string[];
  error?: string;
  derivativeReceipts?: import('../composer/render-port').DerivativeViewReceiptV1[];
}

/**
 * Render one animation clip as a strip of evenly-sampled, phase-labeled frames
 * from a single camera, so the agent can SEE the motion (sideways walk, reverse
 * knee, backward swing, item not tracking the hand). MUTATES `root` (callers pass
 * a freshly executed scene — the tool re-executes per call).
 *
 * Two passes: pose+measure every frame to a union AABB (steady framing so root
 * travel reads), then pose+rasterize+label each frame against that fixed box.
 */
export async function renderClipAnimation(
  root: unknown,
  clips: readonly DuckClip[],
  opts: AnimationViewOptions = {},
): Promise<AnimationViewResult> {
  const size = opts.size ?? 256;
  const frameCount = Math.max(2, Math.min(opts.frames ?? 6, 6));
  const cam = resolveCamera(opts.camera);

  if (!clips || clips.length === 0) {
    return {
      ok: false,
      frames: 0,
      frameTimes: [],
      error: 'this asset has no animation clips',
      availableClips: [],
    };
  }
  // Resolve the requested clip by name; default to the first when none is named.
  const requested = opts.clip?.trim();
  const chosen = requested ? findClip(clips, requested) : clips[0];
  if (!chosen) {
    return {
      ok: false,
      frames: 0,
      frameTimes: [],
      ...(requested ? { clip: requested } : {}),
      error: `clip "${requested}" not found in this asset`,
      availableClips: clipNames(clips),
    };
  }

  const prepared = prepareClip(root as never, chosen);
  if (opts.frameTimes && opts.frames !== undefined)
    throw new Error('frameTimes and frames are mutually exclusive');
  if (opts.shot && opts.camera) throw new Error('shot and camera are mutually exclusive');
  if (
    opts.frameTimes &&
    (opts.frameTimes.length < 1 ||
      opts.frameTimes.length > 9 ||
      opts.frameTimes.some(
        (v, i) => !Number.isFinite(v) || v < 0 || v > 1 || (i > 0 && v <= opts.frameTimes![i - 1]!),
      ))
  )
    throw new Error('frameTimes must contain 1..9 strictly increasing phases in 0..1');
  const times = opts.frameTimes
    ? opts.frameTimes.map((t) => t * prepared.duration)
    : planFrameTimes(prepared.duration, frameCount);
  const frameTimes = times.map((t) => (prepared.duration > 0 ? t / prepared.duration : 0));
  if (opts.measureParts && (opts.measureParts.length < 1 || opts.measureParts.length > 16))
    throw new Error('measureParts must contain 1..16 exact selectors');
  const measuredParts = opts.measureParts?.map((selector) => selectCameraSubject(root, selector));
  if (
    measuredParts &&
    new Set(measuredParts.map((part) => part.node)).size !== measuredParts.length
  )
    throw new Error('measureParts contains duplicate part selections');

  // Pass 1 — measure each pose and union subject bounds for steady framing.
  const min: [number, number, number] = [Infinity, Infinity, Infinity];
  const max: [number, number, number] = [-Infinity, -Infinity, -Infinity];
  const poseBounds: AnimationPoseBounds[] = [];
  for (const [i, t] of times.entries()) {
    poseSceneAtTime(root as never, prepared, t);
    const scene = measureBounds(root);
    const subject = opts.shot?.subject
      ? measureBounds(selectCameraSubject(root, opts.shot.subject).node)
      : undefined;
    poseBounds.push({
      phase: frameTimes[i]!,
      timeSeconds: t,
      scene,
      ...(subject ? { subject } : {}),
      ...(measuredParts
        ? {
            parts: measuredParts.map(({ path, name, node }) => ({
              path,
              name,
              bounds: measurePartBounds(node),
              origin: worldOrigin(node),
            })),
          }
        : {}),
    });
    const b = subject ?? scene;
    for (let a = 0; a < 3; a++) {
      const lo = b.min[a]!;
      const hi = b.max[a]!;
      if (lo < min[a]!) min[a] = lo;
      if (hi > max[a]!) max[a] = hi;
    }
  }
  const frameBounds = Number.isFinite(min[0]) ? { min, max } : undefined;
  poseSceneAtTime(root as never, prepared, times[0]!);
  const initialShot = opts.shot ? resolveAssetCamera(root, opts.shot) : undefined;
  let lockedCamera = initialShot?.camera;
  if (initialShot && opts.shot?.camera?.type !== 'explicit' && frameBounds) {
    const dir = initialShot.camera.position.map((v, i) => v - initialShot.camera.target[i]!) as [
      number,
      number,
      number,
    ];
    lockedCamera = cameraFromBounds(
      frameBounds,
      dir,
      opts.shot?.camera?.type === 'orbit' ? (opts.shot.camera.padding ?? 1.2) : 1.2,
      initialShot.camera.up,
    );
  }
  const lens = opts.shot?.camera;
  if (
    lockedCamera &&
    opts.framing !== 'follow' &&
    lens?.type === 'explicit' &&
    lens.projection === 'perspective' &&
    lens.near === undefined
  ) {
    // A locked camera was placed against the first pose; keep its default near plane
    // short of the scene at every sampled pose, not only the first.
    const union = { min: [...poseBounds[0]!.scene.min], max: [...poseBounds[0]!.scene.max] };
    for (const { scene } of poseBounds)
      for (let a = 0; a < 3; a++) {
        union.min[a] = Math.min(union.min[a]!, scene.min[a]!);
        union.max[a] = Math.max(union.max[a]!, scene.max[a]!);
      }
    lockedCamera = {
      ...lockedCamera,
      near: Math.max(
        0.001,
        Math.min(lockedCamera.near, boxDistance(lockedCamera.position, union) / 2),
      ),
    };
  }
  const cameraShots: ResolvedCameraShotV1[] = [];

  // Pass 2 — render + label each frame against the fixed framing.
  const labelScale = Math.max(2, Math.round(size / 80));
  const cells: Uint8Array[] = [];
  const derivativeReceipts: import('../composer/render-port').DerivativeViewReceiptV1[] = [];
  for (let i = 0; i < times.length; i++) {
    poseSceneAtTime(root as never, prepared, times[i]!);
    const resolvedShot = opts.shot ? resolveAssetCamera(root, opts.shot) : undefined;
    if (resolvedShot) {
      if (opts.framing !== 'follow') resolvedShot.camera = lockedCamera!;
      cameraShots.push(resolvedShot);
    }
    let cell: Uint8Array;
    if (opts.renderDerivativeCell) {
      const produce = () =>
        opts.renderDerivativeCell!({
          root,
          ...(resolvedShot ? { camera: resolvedShot.camera } : {}),
          label: `${Math.round(frameTimes[i]! * 100)}%`,
          view: cam,
          size,
          ...(opts.backfaceCull !== undefined ? { backfaceCull: opts.backfaceCull } : {}),
          ...(frameBounds ? { frameBounds } : {}),
        });
      const rendered = resolvedShot
        ? await withCameraVisibility(root, resolvedShot, produce)
        : await produce();
      const decoded = decodePngShared(rendered.png);
      if (decoded.width !== size || decoded.height !== size) {
        throw new Error(
          `derivative animation cell must be ${size}x${size}; got ${decoded.width}x${decoded.height}`,
        );
      }
      cell = decoded.rgb;
      derivativeReceipts.push(rendered.receipt);
    } else {
      cell = resolvedShot
        ? await withCameraVisibility(root, resolvedShot, async () =>
            rasterizeCamera(root, resolvedShot.camera, size),
          )
        : rasterizeView(root, cam.dir, {
            size,
            ...(opts.backfaceCull !== undefined ? { backfaceCull: opts.backfaceCull } : {}),
            ...(frameBounds ? { frameBounds } : {}),
          });
    }
    stampLabel(
      cell,
      size,
      size,
      labelScale,
      labelScale,
      `${Math.round(frameTimes[i]! * 100)}%`,
      labelScale,
    );
    cells.push(cell);
  }

  const baseMeta = {
    ok: true as const,
    loopClosure: measureLoopClosure(root as never, chosen),
    clip: prepared.name,
    camera: cam.name,
    frames: times.length,
    frameTimes,
    poseBounds,
    ...(cameraShots.length ? { cameraShots } : {}),
    duration: prepared.duration,
    ...(prepared.unresolved.length ? { unresolvedTracks: prepared.unresolved } : {}),
    ...(derivativeReceipts.length ? { derivativeReceipts } : {}),
  };

  if (opts.perFrame) {
    return {
      ...baseMeta,
      width: size,
      height: size,
      pngs: cells.map((c) => encodePng(c, size, size)),
    };
  }

  // Compose into a 3x2 grid (same layout as the six-view grid).
  const { rgb, width, height } = compositeCellGrid(cells, size);
  return { ...baseMeta, width, height, png: encodePng(rgb, width, height) };
}

// =============================================================================
// Interior views — see INSIDE an enterable building, roof off (kiln_view_interior)
// =============================================================================

export interface InteriorGridResult extends ViewGridResult {
  cameraShots?: ResolvedCameraShotV1[];
  perFramePngs?: Buffer[];
  /** Roof subtree roots hidden (0 → no roof resolved: no `roof.` role, no
   *  historical roof name, or an explicit `nodeName` that matched nothing). */
  roofsHidden: number;
  /** Near-wall subtree roots hidden for the eye-level cutaway (0 → not a room()). */
  wallsHidden: number;
  derivativeReceipts?: import('../composer/render-port').DerivativeViewReceiptV1[];
}

export interface InteriorGridOptions extends RasterOptions {
  capture?: CaptureConfig;
  /** Exact-name override: lift this node and its children instead of resolving
   *  the roof semantically. Omit it for the ordinary path — role first, then a
   *  narrow historical-name fallback. */
  nodeName?: string;
  /** Internal exact-derivative renderer; omitted preserves the historical CPU path. */
  renderDerivativeCell?: DerivativeCellRenderer;
}

/** Outward face normals of room() walls, by lowercased name suffix (front faces +X). */
const ROOM_WALL_NORMALS: Array<{ suffix: string; n: [number, number, number] }> = [
  { suffix: 'wallfront', n: [1, 0, 0] },
  { suffix: 'wallback', n: [-1, 0, 0] },
  { suffix: 'wallleft', n: [0, 0, -1] },
  { suffix: 'wallright', n: [0, 0, 1] },
];

export const INTERIOR_VIEWS: ViewSpec[] = [
  { name: 'Floor plan', dir: [0, 1, 0.0001] }, // top-down, roof off
  { name: 'Dollhouse', dir: [0.7, 0.5, 0.7] }, // 3/4 cutaway, roof off
  { name: 'Eye-level', dir: [0.55, 0.35, 0.45] }, // low angle, roof + near walls off
];

function normalizeVec(v: [number, number, number]): [number, number, number] {
  const len = Math.hypot(v[0], v[1], v[2]) || 1;
  return [v[0] / len, v[1] / len, v[2] / len];
}
function dotVec(a: [number, number, number], b: [number, number, number]): number {
  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
}

/**
 * Render an enterable building with its roof — and, for the eye-level cell, the
 * near walls — hidden, so the agent can SEE the interior the six exterior views
 * cannot. Three roof-off cells in one row: Floor plan (top-down, layout +
 * walkability), Dollhouse (3/4 cutaway, fixtures sit on the floor), Eye-level
 * (low angle through the doorway with the camera-facing walls removed, so the
 * doorway reads as a real gap and nothing is buried inside a solid mass).
 *
 * MUTATES `root` (callers pass a freshly executed scene — the tool re-executes
 * per call). Interior faces point AWAY from the camera once the lid/near walls
 * are off, so backface culling is OFF for every cell (the exterior grid keeps it
 * ON to reveal winding bugs).
 */
export async function renderInteriorGrid(
  root: unknown,
  opts: InteriorGridOptions = {},
): Promise<InteriorGridResult> {
  const size = opts.size ?? 256;
  const labelScale = Math.max(2, Math.round(size / 80));

  // Lift the roof once — persists for every cell. Explicit nodeName remains an
  // opt-in compatibility override; ordinary architecture views are semantic
  // first with a narrow historical-name fallback.
  const roofsHidden = opts.nodeName
    ? hideNodeInScene(root, opts.nodeName)
    : hideArchitectureRoofInScene(root).nodes.length;

  if (opts.capture) {
    const grid = await renderCaptureGrid(root, opts.capture, opts.renderDerivativeCell);
    return { ...grid, roofsHidden, wallsHidden: 0 };
  }
  let wallsHidden = 0;
  const cells: Uint8Array[] = [];
  const derivativeReceipts: import('../composer/render-port').DerivativeViewReceiptV1[] = [];
  for (const view of INTERIOR_VIEWS) {
    if (view.name === 'Eye-level') {
      // Cutaway: also remove the walls facing the camera so the eye looks past
      // them onto the far wall + floor. room() names walls `<root>_Wall<Side>`.
      const d = normalizeVec(view.dir);
      wallsHidden = hideNodeInScene(root, (name) => {
        const lower = name.toLowerCase();
        for (const w of ROOM_WALL_NORMALS) {
          if (lower.endsWith(w.suffix) && dotVec(w.n, d) > 0.2) return true;
        }
        return false;
      });
    }
    let cell: Uint8Array;
    if (opts.renderDerivativeCell) {
      const rendered = await opts.renderDerivativeCell({
        root,
        label: view.name,
        view,
        size,
        backfaceCull: false,
      });
      const decoded = decodePngShared(rendered.png);
      if (decoded.width !== size || decoded.height !== size) {
        throw new Error(
          `derivative interior cell must be ${size}x${size}; got ${decoded.width}x${decoded.height}`,
        );
      }
      cell = decoded.rgb;
      derivativeReceipts.push(rendered.receipt);
    } else {
      cell = rasterizeView(root, view.dir, { size, backfaceCull: false });
    }
    stampLabel(cell, size, size, labelScale, labelScale, view.name, labelScale);
    cells.push(cell);
  }

  // Single-row grid (reuse the six-view PAD/PAD_COLOR layout).
  const { rgb, width, height } = compositeCellGrid(cells, size, INTERIOR_VIEWS.length);

  return {
    png: encodePng(rgb, width, height),
    width,
    height,
    views: INTERIOR_VIEWS.map((v) => v.name),
    // The fixed interior row paints the default backdrop; echo it the way every
    // other grid does, so a reader never has to guess what a silhouette sat on.
    capture: {
      preset: 'interior',
      cols: INTERIOR_VIEWS.length,
      cells: INTERIOR_VIEWS.length,
      backdrop: DEFAULT_BACKDROP_ID,
    },
    roofsHidden,
    wallsHidden,
    ...(derivativeReceipts.length ? { derivativeReceipts } : {}),
  };
}