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.

127 KB
Raw Blame
import type { DuckClip } from './views/pose';
import { declaredSupports, type ExternalSupportV1, restingSupport } from './external-support';
import {
  assertNoLegacyRuntimePolicy,
  resolveRequirementsContext,
  type RequirementsContext,
} from './requirements-context';
import type { RequirementsBinding } from './requirements-store';
import {
  runRequirementsSceneQa,
  collectRequirementsSceneEvidence,
  appendRequirementsFinalQa,
} from './qa/requirements-run';
import type { AssetRequirementsQaReportV2 } from './qa/requirements-report';
import { createRequirementsQaReport } from './qa/requirements-report';
import { meshComponentBoxes, splitBudget } from './qa/mesh-components';
import { inspectSkinIntegrity } from './qa/skin-integrity';
import { AuthoringDiagnosticError, rethrowAuthoringError } from './evaluator/authoring-diagnostic';
/**
 * Headless Kiln GLB Renderer
 *
 * Takes Kiln-generated code and produces a binary GLB Buffer.
 * Uses Three.js for scene construction (pure math, no WebGL) and
 * @gltf-transform/core for serialization. No browser APIs required.
 *
 * Ported from scripts/export-glb.ts - same bridge pattern, exposed as a
 * library function so core can be consumed by server/CLI without shelling
 * out.
 */

import * as THREE from 'three';
import { createGltfIO } from './gltf-io';
import { collectLodSets } from './lod';
import { applyLodChains, summarizeLodChains } from './lod-export';
import { applyNodeVisibility, drawnSceneBounds, summarizeHiddenNodes } from './node-visibility';
import { communitySceneDocument, resolveGltfExporter } from './community-exporter';
import {
  collectAtlasProvenance,
  mergeAtlasDocumentProvenance,
  refreshAtlasDocumentProvenance,
  validateAtlasDocumentProvenance,
  type AtlasProvenanceCollection,
} from './atlas-provenance';
import { assertPortableMaterialSides } from './material-export';
import { isCubicSplineTrack } from './animation-spline';
import {
  applyIndexPolicy,
  resolveIndexPolicy,
  type IndexPolicy,
  type IndexBufferReceipt,
} from './index-policy';
import { openShellExtras } from './open-shell';
import { kitExtras, repeatInstancesExtras } from './delivery';
import { inspectDelivery, summarizeVertexAttributes } from './delivery-inspect';
import { SURFACE_BAKE_KEY, surfaceBakeRecord } from './surface-bake';
import { assertRequiredSolids } from './require-solid';
import { writtenNodeResolver } from './written-nodes';
import { rigExtrasForExport } from './rig-export';
import { type AuthorExtras, collectAuthorExtras } from './user-data-extras';
import {
  CUSTOM_EXPORT_ATTRIBUTES,
  customAttributeSemantic,
  geometryAttributeValues,
  unitNormalValues,
  inspectGeometryExport,
  validateMaterialGroups,
  type GeometryExportPolicy,
} from './geometry-export';
import { createHash } from 'node:crypto';
import { Document, Logger, type TextureInfo } from '@gltf-transform/core';
import { KHRMaterialsEmissiveStrength } from '@gltf-transform/extensions';
import { dedup, palette, weld, prune, mergeDocuments } from '@gltf-transform/functions';
import {
  countInstanceBatches,
  instanceByHandedness,
  instancingBlocker,
} from './instance-handedness';

import {
  buildSlotIndex,
  chooseSlot,
  hexToLinearRgb,
  type SnapSlot,
  type SnapPaletteSlot,
} from './palette-snap';

import {
  buildSandboxGlobals,
  countTriangles,
  type DiagnosticConsole,
  SANDBOX_DECLARATIONS,
  type SandboxDeclarations,
} from './primitives';
import {
  declaresMaterialLimits,
  evaluateBudget,
  KILN_BUDGET_KEY,
  normalizeBudget,
  readBudgetDeclaration,
} from './budget';
import {
  evaluatePalette,
  KILN_PALETTE_KEY,
  normalizePalette,
  readPaletteDeclaration,
} from './palette-check';
import {
  collectGlbMetrics,
  gradeInstanceability,
  materialMergeCandidates,
  type InstanceabilityGrade,
  type InstanceabilityMetrics,
  type InstanceabilityReport,
} from './metrics';
import {
  cloneSemanticMetadataV1,
  createSemanticMetadataV1,
  KILN_SEMANTIC_EXTRAS_KEY,
  validateSemanticMetadataV1,
  type AssetCategory,
  type AssetIntentV1,
  type IntegrationAssetRole,
  type IntegrationManifestV1,
} from './contracts';
import {
  assertFinalGlbValid,
  GltfValidationError,
  validateFinalGlbBytes,
  type KhronosGltfValidationReport,
} from './qa/gltf';
import { AssetQaBlockedError, qaBlockingEnabled, qaPolicyFromEnv } from './qa/run';
import {
  adviseMaterialsV1,
  collectMaterialMetricsV1,
  DEFAULT_MATERIAL_REFERENCE,
  type MaterialAdviceV1,
  type MaterialMetricsV1,
} from './material-metrics';
import {
  collectMaterialRecipeApplications,
  type MaterialRecipeApplicationProvenanceV1,
} from './material-recipe-runtime';
import {
  collectMaterialResourceProvenance,
  type MaterialResourceProvenanceV1,
} from './material-resources';
import { DEFAULT_TEXTURE_RESOLVER, type TextureResolver } from './texture-resolver';
import type { MaterialLibraryPayload, MaterialManifest } from './material-library';
import { FULL_OPTIMIZATION_PIPELINE, type RebuildOptions } from './rebuild-options';
import { rigidMerge, type RigidMergeSummary } from './rigid-merge';
import { assertGeneratedSourceSafe } from './validation';
import { applyKitContract, type KitPackOptions, type KitPackSummary } from './kit';
import {
  type BakedTextureProvenanceV1,
  bakeSceneTextures,
  ensureNormalMapTangents,
} from './texture-bake';
import type { CharacterCapturedDiagnosticV1 } from './views/character-capture';
import type { VehicleCapturedDiagnosticV1 } from './views/vehicle';

export type CapturedDiagnosticV1 = CharacterCapturedDiagnosticV1 | VehicleCapturedDiagnosticV1;

// WebIO (not NodeIO) is used for GLB serialization so the same code path
// works in both Node and browser environments. writeBinary() only builds the
// GLB byte stream in memory - it never reads URIs - so the fetch/fs gap
// between WebIO and NodeIO is irrelevant on the write side. This lets the
// editor's exportGLB() and headless renderGLB() share one bridge.

/** Engine-standard glTF IO: WebIO with the extensions Kiln GLBs may carry.
 *  EXT_mesh_gpu_instancing must be REGISTERED on the read side or a re-read
 *  (grade-from-bytes, optimize-from-bytes, palette snap) would silently drop
 *  the instancing a prior bake emitted — the batch node would collapse to a
 *  single copy. Write-side registration is harmless (the extension instance
 *  travels on the Document). */
// Variants and Basisu are registered for READS as much as writes: once the kit
// pass has run, every later pass that parses these bytes (metrics, optimize,
// palette snap) would silently drop both extensions without them.
const engineIO = createGltfIO;

/**
 * World-space AABB of a stored GLB, computed from its bytes alone — node
 * transforms applied over the (spec-required) POSITION accessor bounds. No
 * model-authored code is executed: this exists so consumers that only hold the
 * artifact (e.g. Kiln Studio's compose catalog fallback, H-41) never need
 * `executeKilnCode` to recover a footprint. Caveat: EXT_mesh_gpu_instancing
 * copies are not expanded (the batch node contributes its single-copy bounds);
 * records new enough to be instanced also persist `metrics.bbox`, so the
 * from-bytes path is a legacy-record fallback. Returns undefined for a GLB with
 * no measurable geometry.
 */
export async function measureGlbBounds(
  bytes: Uint8Array,
): Promise<{ min: [number, number, number]; max: [number, number, number] } | undefined> {
  const doc = await engineIO().readBinary(bytes);
  const root = doc.getRoot();
  const scene = root.getDefaultScene() ?? root.listScenes()[0];
  if (!scene) return undefined;
  const { min, max } = drawnSceneBounds(scene);
  if (!min.every(Number.isFinite) || !max.every(Number.isFinite)) return undefined;
  return {
    min: [min[0]!, min[1]!, min[2]!],
    max: [max[0]!, max[1]!, max[2]!],
  };
}

/**
 * Record each baked mesh's parameters as its glTF mesh extras `kilnSurfaceBakeV1`, keyed by
 * glTF attribute name, so the bytes alone say how `_EDGE` and `_CAVITY` were made. Runs on
 * either converter's document before any pass moves nodes.
 */
function applySurfaceBakeExtras(root: THREE.Object3D, doc: Document): void {
  const baked: Array<[THREE.Object3D, Record<string, unknown>]> = [];
  root.traverse((node) => {
    const mesh = node as THREE.Mesh;
    const record = mesh.isMesh ? surfaceBakeRecord(mesh.geometry) : undefined;
    if (record && Object.keys(record).length) baked.push([mesh, { ...record }]);
  });
  if (baked.length === 0) return;
  const written = writtenNodeResolver(root, doc, 'Surface bake export');
  for (const [node, record] of baked) {
    const mesh = written(node).getMesh();
    if (mesh) mesh.setExtras({ ...mesh.getExtras(), [SURFACE_BAKE_KEY]: record });
  }
}

/** Triangles a loader does not draw: hidden subtrees outside the lower LOD levels. */
function hiddenTriangles(root: THREE.Object3D, lowerLevels: ReadonlySet<THREE.Object3D>): number {
  let hidden = 0;
  const visit = (node: THREE.Object3D): void => {
    if (lowerLevels.has(node)) return;
    if (node.visible === false) {
      hidden += countTriangles(node);
      return;
    }
    for (const child of node.children) visit(child);
  };
  visit(root);
  return hidden;
}

// Gltf-transform type aliases for local readability.
type GtNode = import('@gltf-transform/core').Node;
type GtMesh = import('@gltf-transform/core').Mesh;
type GtMaterial = import('@gltf-transform/core').Material;
type GtBuffer = import('@gltf-transform/core').Buffer;
type GtTexture = import('@gltf-transform/core').Texture;
type GtScene = import('@gltf-transform/core').Scene;

// Accessor.Type is typed as Record<string, AccessorType> which runs afoul of
// noUncheckedIndexedAccess. Use the literal strings directly - same values,
// no type noise.
type AccessorTypeStr = 'SCALAR' | 'VEC2' | 'VEC3' | 'VEC4' | 'MAT2' | 'MAT3' | 'MAT4';
const TYPE_SCALAR: AccessorTypeStr = 'SCALAR';
const TYPE_VEC2: AccessorTypeStr = 'VEC2';
const TYPE_VEC3: AccessorTypeStr = 'VEC3';
const TYPE_VEC4: AccessorTypeStr = 'VEC4';
/** Accessor type by component count, 1 to 4. */
const ACCESSOR_TYPES = [TYPE_SCALAR, TYPE_VEC2, TYPE_VEC3, TYPE_VEC4] as const;

// =============================================================================
// Execution
// =============================================================================

/**
 * Scene-placement role the agent declares in its `meta` block. Drives composer
 * layout (wonders anchor + scale up, fill scatters, ground is the base, vehicles
 * snap to roads) and Kiln City density budgeting. Semantic — cannot be recomputed
 * from GLB bytes, so it travels in provenance. See plan/05-product-depth.md §3.4.
 */
export type AssetRole = IntegrationAssetRole;
export type { SnapPaletteSlot } from './palette-snap';

const GROUND_CONTACT_TOLERANCE = 0.02;

function ensureDefaultScene(doc: Document): GtScene | undefined {
  const root = doc.getRoot();
  const scene = root.getDefaultScene() ?? root.listScenes()[0];
  if (scene && !root.getDefaultScene()) root.setDefaultScene(scene);
  return scene;
}

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

/** Inspect finished bytes without executing model-authored source code. */
export async function inspectGlbIntegration(
  bytes: Uint8Array,
  opts: {
    requestedRole?: IntegrationAssetRole;
    assessedRole?: IntegrationAssetRole;
    validation?: KhronosGltfValidationReport;
  } = {},
): Promise<IntegrationManifestV1 | undefined> {
  const doc = await engineIO().readBinary(bytes);
  const root = doc.getRoot();
  const explicitDefault = root.getDefaultScene();
  const scene = explicitDefault ?? root.listScenes()[0];
  if (!scene) return undefined;

  // What a loader draws: hidden subtrees are listed apart below.
  const { min, max } = drawnSceneBounds(scene);
  const finiteBounds = min.every(Number.isFinite) && max.every(Number.isFinite);
  if (!finiteBounds) return undefined;
  const metrics = collectGlbMetrics(doc);
  const validation = opts.validation ?? (await validateFinalGlbBytes(bytes));
  const scenes = root.listScenes();
  const minTuple: [number, number, number] = [min[0]!, min[1]!, min[2]!];
  const maxTuple: [number, number, number] = [max[0]!, max[1]!, max[2]!];
  const minY = minTuple[1];
  const levelsOfDetail = summarizeLodChains(doc);
  const hiddenNodes = summarizeHiddenNodes(doc);
  const delivery = inspectDelivery(doc);
  const vertexAttributes = summarizeVertexAttributes(doc);
  const budgetDeclaration = readBudgetDeclaration(
    (scene.getExtras() as Record<string, unknown>)[KILN_BUDGET_KEY],
  );
  // The instanced estimate runs the three target's batching on a copy, so it is loaded
  // only when a draws cap is declared.
  const instancedDraws =
    budgetDeclaration?.draws === undefined
      ? undefined
      : await (await import('./runtime-three')).instancedDrawEstimate(doc);
  const materialMetrics = collectMaterialMetricsV1(doc);
  const budget = budgetDeclaration
    ? evaluateBudget(
        budgetDeclaration,
        {
          triangles: metrics.triangles,
          draws: metrics.drawCalls,
          ...(instancedDraws === undefined ? {} : { instancedDraws }),
        },
        levelsOfDetail,
        materialMetrics,
      )
    : undefined;
  // Reference-tier notes only where the author declared no material limit of their own.
  const materialAdvice = declaresMaterialLimits(budgetDeclaration)
    ? []
    : adviseMaterialsV1(materialMetrics, DEFAULT_MATERIAL_REFERENCE);
  const paletteDeclaration = readPaletteDeclaration(
    (scene.getExtras() as Record<string, unknown>)[KILN_PALETTE_KEY],
  );
  const palette = paletteDeclaration ? evaluatePalette(paletteDeclaration, doc) : undefined;

  return {
    schemaVersion: 'kiln.integration-manifest.v1',
    analyzerVersion: 1,
    artifactSha256: await sha256Hex(bytes),
    units: 'm',
    axes: { forward: '+X', up: '+Y', right: '+Z' },
    bounds: {
      min: minTuple,
      max: maxTuple,
      size: [maxTuple[0] - minTuple[0], maxTuple[1] - minTuple[1], maxTuple[2] - minTuple[2]],
      center: [
        (minTuple[0] + maxTuple[0]) / 2,
        (minTuple[1] + maxTuple[1]) / 2,
        (minTuple[2] + maxTuple[2]) / 2,
      ],
    },
    pivot: { convention: 'author-origin', position: [0, 0, 0] },
    ground: {
      groundY: 0,
      contactTolerance: GROUND_CONTACT_TOLERANCE,
      minY,
      offsetToGround: -minY,
      grounded: Math.abs(minY) <= GROUND_CONTACT_TOLERANCE,
    },
    defaultScene: { index: scenes.indexOf(scene), name: scene.getName() },
    ...(opts.requestedRole ? { requestedRole: opts.requestedRole } : {}),
    ...(opts.assessedRole ? { assessedRole: opts.assessedRole } : {}),
    renderMetrics: {
      triangles: metrics.triangles,
      drawCalls: metrics.drawCalls,
      uniqueGeometries: metrics.uniqueGeometries,
      uniqueMaterials: metrics.uniqueMaterials,
      textureCount: metrics.textureCount,
      transparentMaterials: metrics.transparentMaterials,
      skinned: metrics.skinned,
    },
    ...(levelsOfDetail.length ? { levelsOfDetail } : {}),
    ...(hiddenNodes.length ? { hiddenNodes } : {}),
    ...(delivery.colliders.length ? { colliders: delivery.colliders } : {}),
    ...(delivery.anchors.length ? { anchors: delivery.anchors } : {}),
    ...(delivery.kit ? { kit: delivery.kit } : {}),
    ...(delivery.ports.length ? { ports: delivery.ports } : {}),
    ...(budget ? { budget } : {}),
    ...(materialAdvice.length ? { materialAdvice } : {}),
    ...(palette ? { palette } : {}),
    ...(vertexAttributes.length ? { vertexAttributes } : {}),
    ...(delivery.diagnostics.length ? { deliveryDiagnostics: delivery.diagnostics } : {}),
    structuralQa: {
      hasDefaultScene: explicitDefault !== null,
      finiteBounds,
      validatorErrors: validation.issues.numErrors,
      validatorWarnings: validation.issues.numWarnings,
    },
    visualQa: 'not_assessed',
  };
}

export interface KilnCodeMeta {
  indexBuffers?: IndexBufferReceipt;
  name?: string;
  category?: string;
  /** Scene-placement role (agent-declared). Drives composer layout + city budgeting. */
  role?: AssetRole;
  tris?: number;
  /**
   * Count of primitive invocations from the agent-generated build() call.
   * Populated by executeKilnCode / renderGLB; agents don't author this.
   * Used to drive primitive-library prioritization from real usage.
   */
  primitiveUsage?: Record<string, number>;
  /**
   * Instanceability metrics measured against the post-dedup() glTF Document.
   * Informational only — never a gate. Populated by renderGLB / renderSceneToGLB.
   */
  instanceability?: InstanceabilityReport;
  /**
   * Convenience copy of {@link KilnCodeMeta.instanceability}.grade (A–F),
   * auto-filled at bake so consumers read the tier without re-deriving it.
   */
  tier?: InstanceabilityGrade;
  /** Set if metric computation threw; the GLB is still valid. */
  metricsError?: string;
  /** Set when an opt-in consolidation pass ran (optimize !== 'off'). */
  optimize?: OptimizeSummary;
  /** Set when the GPU-instancing pass created batches (M1c — perf, not grade). */
  instancing?: InstancingSummary;
  [key: string]: unknown;
}

export interface ExecutedKilnCode {
  meta: KilnCodeMeta;
  root: THREE.Object3D;
  clips: THREE.AnimationClip[];
  /**
   * Primitive-call counts gathered while executing build()/animate().
   * Identical to meta.primitiveUsage once renderGLB merges it in.
   */
  primitiveUsage: Record<string, number>;
}

/**
 * Execute Kiln-generated code in a Function sandbox and return the built
 * Three.js scene plus animation clips. Throws on any runtime error in the
 * generated code.
 */
/**
 * Execute generated Kiln code and return the built scene + clips.
 *
 * Async because CSG primitives (boolUnion, boolDiff, etc.) are WASM-backed
 * and async. Sync `build()` functions are supported transparently — if the
 * return value is a Promise it is awaited, otherwise it is used as-is.
 * Same for `animate()`.
 */
export interface ExecuteKilnCodeOptions {
  /** Trusted host injection. Generated source receives only the closed
   *  loadApprovedTexture(resourceId) function. */
  textureResolver?: TextureResolver;
  /** Trusted diagnostic sink, never a global console mutation. */
  console?: DiagnosticConsole;
}

export async function executeKilnCode(
  code: string,
  options: ExecuteKilnCodeOptions = {},
): Promise<ExecutedKilnCode> {
  if (!code || typeof code !== 'string') {
    throw new Error('executeKilnCode: code must be a non-empty string');
  }

  // Normalize line endings - Windows CRLF from LLM responses trips up the
  // Function constructor.
  const normalized = code.replace(/\r\n/g, '\n');

  // Defense in depth only: reject known ambient/dynamic-code escape patterns
  // before the Function constructor sees source. This is not process isolation.
  assertGeneratedSourceSafe(normalized);

  try {
    const primitiveUsage: Record<string, number> = {};
    const globals = buildSandboxGlobals(primitiveUsage, {
      textureResolver: options.textureResolver ?? DEFAULT_TEXTURE_RESOLVER,
      console: options.console,
    });
    const globalNames = Object.keys(globals);
    const globalValues = Object.values(globals);

    // Generated code runs in strict mode: `this` outside a method is undefined rather
    // than the host global, an undeclared assignment throws instead of creating a
    // global, and a block-level function stays in its block. Validation parses with
    // the same directive (decision 23 of 2 October 2026).
    const fn = new Function(
      ...globalNames,
      `'use strict';\n${normalized}\nreturn { meta: typeof meta !== 'undefined' ? meta : {}, build, animate: typeof animate !== 'undefined' ? animate : null };`,
    );

    const { meta, build, animate } = fn(...globalValues) as {
      meta: KilnCodeMeta;
      build: () => THREE.Object3D | Promise<THREE.Object3D>;
      animate:
        | ((
            root: THREE.Object3D,
          ) => THREE.AnimationClip[] | undefined | Promise<THREE.AnimationClip[] | undefined>)
        | null;
    };

    if (typeof build !== 'function') {
      throw new AuthoringDiagnosticError(
        'BUILD_RESULT',
        'executeKilnCode: generated code did not define `build`',
      );
    }

    const root = await build();
    // Duck-typed check — the kiln sandbox uses `new Function(...)`, which under
    // bun creates an isolated module realm. `new THREE.X()` inside the sandbox
    // produces objects whose constructor is a *different* class object from the
    // THREE imported here, so `instanceof THREE.Object3D` returns false.
    // Three.js sets `.isObject3D = true` on the prototype for exactly this case.
    if (!(root as { isObject3D?: boolean })?.isObject3D) {
      throw new AuthoringDiagnosticError(
        'BUILD_RESULT',
        'executeKilnCode: build() did not return a THREE.Object3D',
      );
    }

    // Node-less declarations (defineBudget without a target) belong to the returned root.
    const declared = (globals as { [SANDBOX_DECLARATIONS]?: SandboxDeclarations })[
      SANDBOX_DECLARATIONS
    ];
    if (declared?.budget && root.userData[KILN_BUDGET_KEY] === undefined)
      root.userData[KILN_BUDGET_KEY] = declared.budget;
    if (declared?.palette && root.userData[KILN_PALETTE_KEY] === undefined)
      root.userData[KILN_PALETTE_KEY] = declared.palette;

    const clips = animate ? ((await animate(root)) ?? []) : [];

    return { meta: meta ?? {}, root, clips, primitiveUsage };
  } catch (error) {
    rethrowAuthoringError(error);
  }
}

// =============================================================================
// Three.js -> gltf-transform Bridge
// =============================================================================

/**
 * Write the emitted colour Three.js renders, `emissive * emissiveIntensity`.
 * Core glTF clamps `emissiveFactor` to [0, 1], so a product within range is the
 * factor alone; above 1 the factor is normalized by its largest channel and
 * `KHR_materials_emissive_strength` carries that channel's value.
 */
function bridgeEmissive(
  doc: Document,
  target: GtMaterial,
  source: { emissive?: THREE.Color; emissiveIntensity?: number },
): void {
  const color = source.emissive;
  if (!color) return;
  const intensity = source.emissiveIntensity ?? 1;
  // Emission cannot be negative in glTF. A non-finite intensity is blocked by
  // material QA; keep the authored colour rather than write a NaN factor.
  const scale = Number.isFinite(intensity) ? Math.max(0, intensity) : 1;
  const emitted: [number, number, number] = [color.r * scale, color.g * scale, color.b * scale];
  const peak = Math.max(...emitted);
  if (!(peak > 1)) {
    target.setEmissiveFactor(emitted);
    return;
  }
  target.setEmissiveFactor([emitted[0] / peak, emitted[1] / peak, emitted[2] / peak]);
  target.setExtension(
    'KHR_materials_emissive_strength',
    doc
      .createExtension(KHRMaterialsEmissiveStrength)
      .createEmissiveStrength()
      .setEmissiveStrength(peak),
  );
}

const GLTF_MIN_FILTER = {
  [THREE.NearestFilter]: 9728,
  [THREE.LinearFilter]: 9729,
  [THREE.NearestMipmapNearestFilter]: 9984,
  [THREE.LinearMipmapNearestFilter]: 9985,
  [THREE.NearestMipmapLinearFilter]: 9986,
  [THREE.LinearMipmapLinearFilter]: 9987,
} as const;
const GLTF_MAG_FILTER = { [THREE.NearestFilter]: 9728, [THREE.LinearFilter]: 9729 } as const;
const GLTF_WRAP = {
  [THREE.ClampToEdgeWrapping]: 33071,
  [THREE.MirroredRepeatWrapping]: 33648,
  [THREE.RepeatWrapping]: 10497,
} as const;

/** Samplers belong to each texture use, not the cached glTF image. */
function bridgeTextureSampler(
  source: THREE.Texture,
  target: TextureInfo,
  atlas?: AtlasProvenanceCollection,
): void {
  const min = GLTF_MIN_FILTER[source.minFilter];
  const mag = GLTF_MAG_FILTER[source.magFilter];
  const s = GLTF_WRAP[source.wrapS];
  const t = GLTF_WRAP[source.wrapT];
  for (const [property, value] of [
    ['minFilter', min],
    ['magFilter', mag],
    ['wrapS', s],
    ['wrapT', t],
  ] as const) {
    if (typeof source[property] !== 'number' || value === undefined) {
      throw new TypeError(
        `${source.name || '(unnamed texture)'}: unsupported ${property} ${source[property]}`,
      );
    }
  }
  target.setMinFilter(min).setMagFilter(mag).setWrapS(s).setWrapT(t);
  // Export inspection has already refused channels the geometry cannot supply.
  if (source.channel === 1) target.setTexCoord(1);
  const ref = atlas?.texture(source);
  if (ref) target.setExtras({ ...target.getExtras(), kilnAtlasReference: ref });
}

function bridgeMaterial(
  doc: Document,
  threeMat: THREE.Material,
  cache: Map<THREE.Material, GtMaterial>,
  textureCache: Map<THREE.Texture, GtTexture>,
  authorExtras?: AuthorExtras,
  atlas?: AtlasProvenanceCollection,
): GtMaterial {
  const cached = cache.get(threeMat);
  if (cached) return cached;

  const mat = doc.createMaterial(threeMat.name || undefined);
  const author = authorExtras?.material(threeMat);
  if (author) mat.setExtras(author);

  // Duck-typed material checks — see executeKilnCode for the rationale.
  // Sandbox-created materials are different class instances of the same
  // module, so `.isXMaterial` is the only reliable identity test.
  const matFlags = threeMat as unknown as {
    isMeshStandardMaterial?: boolean;
    isMeshLambertMaterial?: boolean;
    isMeshBasicMaterial?: boolean;
    isSpriteMaterial?: boolean;
  };
  if (matFlags.isMeshStandardMaterial) {
    const stdMat = threeMat as THREE.MeshStandardMaterial;
    mat.setBaseColorFactor([stdMat.color.r, stdMat.color.g, stdMat.color.b, stdMat.opacity]);
    mat.setRoughnessFactor(stdMat.roughness);
    mat.setMetallicFactor(stdMat.metalness);
    bridgeEmissive(doc, mat, stdMat);
    if (stdMat.alphaTest > 0) {
      mat.setAlphaMode('MASK');
      mat.setAlphaCutoff(stdMat.alphaTest);
    } else if (stdMat.transparent) {
      mat.setAlphaMode('BLEND');
    }
    if (stdMat.side === THREE.DoubleSide) {
      mat.setDoubleSided(true);
    }
    // PBR texture slots (Wave 3B)
    if (stdMat.map) {
      const t = bridgeTexture(doc, stdMat.map, textureCache);
      if (t) {
        mat.setBaseColorTexture(t);
        bridgeTextureSampler(stdMat.map, mat.getBaseColorTextureInfo()!, atlas);
      }
    }
    if (stdMat.normalMap) {
      const t = bridgeTexture(doc, stdMat.normalMap, textureCache);
      if (t) {
        mat.setNormalTexture(t);
        bridgeTextureSampler(stdMat.normalMap, mat.getNormalTextureInfo()!, atlas);
      }
    }
    // metallic + roughness live in one glTF texture (R=unused, G=rough, B=metal).
    // If the agent used separate Three.js maps we emit the roughness one as
    // the combined channel — the common case is a single combined map anyway.
    if (stdMat.roughnessMap && stdMat.metalnessMap && stdMat.roughnessMap !== stdMat.metalnessMap) {
      throw new TypeError(
        `Material ${JSON.stringify(threeMat.name || '(unnamed)')} uses separate roughness/metalness textures. Pack G=roughness/B=metalness before export.`,
      );
    }
    const mrSource = stdMat.roughnessMap ?? stdMat.metalnessMap;
    if (mrSource) {
      const t = bridgeTexture(doc, mrSource, textureCache);
      if (t) {
        mat.setMetallicRoughnessTexture(t);
        bridgeTextureSampler(mrSource, mat.getMetallicRoughnessTextureInfo()!, atlas);
      }
    }
    if (stdMat.emissiveMap) {
      const t = bridgeTexture(doc, stdMat.emissiveMap, textureCache);
      if (t) {
        mat.setEmissiveTexture(t);
        bridgeTextureSampler(stdMat.emissiveMap, mat.getEmissiveTextureInfo()!, atlas);
      }
    }
    if (stdMat.aoMap) {
      const t = bridgeTexture(doc, stdMat.aoMap, textureCache);
      if (t) {
        mat.setOcclusionTexture(t);
        bridgeTextureSampler(stdMat.aoMap, mat.getOcclusionTextureInfo()!, atlas);
      }
      mat.setOcclusionStrength(stdMat.aoMapIntensity ?? 1);
    }
  } else if (matFlags.isMeshLambertMaterial) {
    const lambMat = threeMat as THREE.MeshLambertMaterial;
    mat.setBaseColorFactor([lambMat.color.r, lambMat.color.g, lambMat.color.b, lambMat.opacity]);
    mat.setRoughnessFactor(1.0);
    mat.setMetallicFactor(0.0);
    bridgeEmissive(doc, mat, lambMat);
  } else if (matFlags.isMeshBasicMaterial) {
    const basicMat = threeMat as THREE.MeshBasicMaterial;
    mat.setBaseColorFactor([
      basicMat.color.r,
      basicMat.color.g,
      basicMat.color.b,
      basicMat.opacity,
    ]);
    mat.setRoughnessFactor(1.0);
    mat.setMetallicFactor(0.0);
  } else if (matFlags.isSpriteMaterial) {
    const spriteMat = threeMat as THREE.SpriteMaterial;
    mat.setBaseColorFactor([
      spriteMat.color.r,
      spriteMat.color.g,
      spriteMat.color.b,
      spriteMat.opacity,
    ]);
    mat.setRoughnessFactor(1.0);
    mat.setMetallicFactor(0.0);
  }

  // Material alpha/sidedness is shared across Three.js material families.
  // Keep this after the family-specific PBR mapping so SpriteMaterial and
  // MeshBasic/Lambert materials cannot pass scene QA and then become opaque or
  // single-sided in the GLB bridge.
  const common = threeMat as THREE.Material & {
    alphaTest?: number;
    transparent?: boolean;
    opacity?: number;
    map?: THREE.Texture | null;
  };
  if ((common.alphaTest ?? 0) > 0) {
    mat.setAlphaMode('MASK');
    mat.setAlphaCutoff(common.alphaTest ?? 0.5);
  } else if (common.transparent || (common.opacity ?? 1) < 1) {
    mat.setAlphaMode('BLEND');
  }
  if (threeMat.side === THREE.DoubleSide) mat.setDoubleSided(true);
  if (common.map && !mat.getBaseColorTexture()) {
    const texture = bridgeTexture(doc, common.map, textureCache);
    if (texture) {
      mat.setBaseColorTexture(texture);
      bridgeTextureSampler(common.map, mat.getBaseColorTextureInfo()!, atlas);
    }
  }

  cache.set(threeMat, mat);
  return mat;
}

/**
 * Bridge a Three.js Texture to a gltf-transform Texture.
 *
 * Uses `userData.encoded` — the bytes `loadTexture` stashed, or the PNG
 * `bakeSceneTextures` encoded earlier in `renderSceneToGLB` — so nothing is
 * re-encoded here.
 *
 * Returning null still drops the slot, but it is no longer silent: the bake
 * pass has already walked every material slot and warned by material and slot
 * name for anything it could not encode. That warning lives there rather than
 * here because this function receives a bare `THREE.Texture` and cannot say
 * which material or slot it came from — which is most of what makes the
 * warning actionable.
 */
function bridgeTexture(
  doc: Document,
  threeTex: THREE.Texture,
  cache: Map<THREE.Texture, GtTexture>,
): GtTexture | null {
  const cached = cache.get(threeTex);
  if (cached) return cached;

  const encoded = (threeTex.userData as Record<string, unknown>)['encoded'] as
    | { mime: string; bytes: Uint8Array }
    | undefined;
  if (!encoded) return null;

  const t = doc.createTexture(threeTex.name || 'texture');
  t.setMimeType(encoded.mime);
  t.setImage(encoded.bytes);
  cache.set(threeTex, t);
  return t;
}

function bridgeGeometry(
  doc: Document,
  buf: GtBuffer,
  geometry: THREE.BufferGeometry,
  material: GtMaterial | GtMaterial[],
  meshName: string,
  atlas?: AtlasProvenanceCollection,
): GtMesh {
  if (!geometry.getAttribute('normal')) {
    geometry.computeVertexNormals();
  }

  const prim = doc.createPrimitive().setMaterial(Array.isArray(material) ? material[0]! : material);

  const posAttr = geometry.getAttribute('position') as THREE.BufferAttribute | undefined;
  if (posAttr) {
    prim.setAttribute(
      'POSITION',
      doc
        .createAccessor(`${meshName}_pos`)
        .setArray(geometryAttributeValues(posAttr))
        .setType(TYPE_VEC3)
        .setBuffer(buf),
    );
  }

  const normAttr = geometry.getAttribute('normal') as THREE.BufferAttribute | undefined;
  if (normAttr) {
    prim.setAttribute(
      'NORMAL',
      doc
        .createAccessor(`${meshName}_norm`)
        .setArray(unitNormalValues(normAttr))
        .setType(TYPE_VEC3)
        .setBuffer(buf),
    );
  }

  const uvAttr = geometry.getAttribute('uv') as THREE.BufferAttribute | undefined;
  if (uvAttr) {
    prim.setAttribute(
      'TEXCOORD_0',
      doc
        .createAccessor(`${meshName}_uv`)
        .setArray(geometryAttributeValues(uvAttr))
        .setType(TYPE_VEC2)
        .setBuffer(buf),
    );
  }

  const uv1Attr = geometry.getAttribute('uv1') as THREE.BufferAttribute | undefined;
  if (uv1Attr) {
    prim.setAttribute(
      'TEXCOORD_1',
      doc
        .createAccessor(`${meshName}_uv1`)
        .setArray(geometryAttributeValues(uv1Attr))
        .setType(TYPE_VEC2)
        .setBuffer(buf),
    );
  }

  const tangentAttr = geometry.getAttribute('tangent') as THREE.BufferAttribute | undefined;
  if (tangentAttr?.itemSize === 4) {
    prim.setAttribute(
      'TANGENT',
      doc
        .createAccessor(`${meshName}_tangent`)
        .setArray(geometryAttributeValues(tangentAttr))
        .setType(TYPE_VEC4)
        .setBuffer(buf),
    );
  }

  const colorAttr = geometry.getAttribute('color') as THREE.BufferAttribute | undefined;
  if (colorAttr?.itemSize === 3 || colorAttr?.itemSize === 4) {
    prim.setAttribute(
      'COLOR_0',
      doc
        .createAccessor(`${meshName}_color`)
        .setArray(geometryAttributeValues(colorAttr))
        .setType(colorAttr.itemSize === 4 ? TYPE_VEC4 : TYPE_VEC3)
        .setBuffer(buf),
    );
  }

  // Baked attributes keep their established order; author attributes follow in name order.
  const customKeys = [
    ...Object.keys(CUSTOM_EXPORT_ATTRIBUTES),
    ...Object.keys(geometry.attributes)
      .filter((key) => !(key in CUSTOM_EXPORT_ATTRIBUTES))
      .sort(),
  ];
  for (const key of customKeys) {
    const gltfName = customAttributeSemantic(key);
    const custom = geometry.getAttribute(key) as THREE.BufferAttribute | undefined;
    if (!gltfName || !custom || custom.itemSize < 1 || custom.itemSize > 4) continue;
    prim.setAttribute(
      gltfName,
      doc
        .createAccessor(`${meshName}${gltfName.toLowerCase()}`)
        .setArray(geometryAttributeValues(custom))
        .setType(ACCESSOR_TYPES[custom.itemSize - 1]!)
        .setBuffer(buf),
    );
  }

  const indexAttr = geometry.getIndex();
  if (indexAttr) {
    // Uint16 holds indices up to 65535; a geometry with more vertices needs
    // Uint32 indices or the values silently wrap (corrupt GLB). gltf-transform
    // derives componentType (5123 vs 5125) from the typed-array class.
    const IndexArray = posAttr && posAttr.count > 65535 ? Uint32Array : Uint16Array;
    prim.setIndices(
      doc
        .createAccessor(`${meshName}_idx`)
        .setArray(new IndexArray(indexAttr.array))
        .setType(TYPE_SCALAR)
        .setBuffer(buf),
    );
  }

  const binding = atlas?.binding(geometry);
  if (binding) prim.setExtras({ kilnAtlasBinding: binding });
  const mesh = doc.createMesh(meshName);
  if (!Array.isArray(material)) return mesh.addPrimitive(prim);
  const indexValues = indexAttr
    ? Array.from(indexAttr.array)
    : Array.from({ length: posAttr!.count }, (_, i) => i);
  const groups = validateMaterialGroups(geometry, material.length, meshName);
  for (const group of groups) {
    const part = doc.createPrimitive().setMaterial(material[group.materialIndex ?? 0]!);
    for (const semantic of prim.listSemantics())
      part.setAttribute(semantic, prim.getAttribute(semantic)!);
    const IndexArray = posAttr!.count > 65535 ? Uint32Array : Uint16Array;
    part.setIndices(
      doc
        .createAccessor(`${meshName}_group_indices`)
        .setArray(new IndexArray(indexValues.slice(group.start, group.start + group.count)))
        .setType(TYPE_SCALAR)
        .setBuffer(buf),
    );
    if (binding) part.setExtras({ kilnAtlasBinding: binding });
    mesh.addPrimitive(part);
  }
  prim.dispose();
  return mesh;
}

function bridgeNode(
  doc: Document,
  buf: GtBuffer,
  threeObj: THREE.Object3D,
  matCache: Map<THREE.Material, GtMaterial>,
  nodeMap: Map<string, GtNode>,
  meshCache: Map<string, GtMesh>,
  texCache: Map<THREE.Texture, GtTexture>,
  authorExtras?: AuthorExtras,
  atlas?: AtlasProvenanceCollection,
): GtNode {
  const gtNode = doc.createNode(threeObj.name || undefined);

  // Author userData reaches extras only through `collectAuthorExtras` (plain JSON, no
  // `kiln*` key, bounded); the engine's own reserved payloads are promoted here only
  // after validation. A malformed reserved payload is an authoring error rather than
  // something the bridge may silently drop.
  const semanticValue = threeObj.userData[KILN_SEMANTIC_EXTRAS_KEY];
  const extras = {
    ...authorExtras?.node(threeObj),
    ...rigExtrasForExport(threeObj),
    ...openShellExtras(threeObj),
    ...kitExtras(threeObj),
    ...repeatInstancesExtras(threeObj),
  };
  let semanticForExport = semanticValue;
  if ((threeObj as THREE.Object3D & { isSprite?: boolean }).isSprite) {
    // glTF has no native Sprite primitive. The bridge emits a quad below and
    // stamps the actual Three.js spherical-facing behavior as a portable
    // semantic so a runtime consumer can reconstruct it deterministically.
    if (semanticValue === undefined) {
      semanticForExport = createSemanticMetadataV1({
        roles: ['vfx.facing.camera-spherical', 'vfx.effect.surface.card'],
      });
    } else {
      const existing = validateSemanticMetadataV1(semanticValue);
      if (existing.valid && existing.value) {
        semanticForExport = {
          ...cloneSemanticMetadataV1(existing.value),
          roles: [
            // The exporter owns the runtime truth for Sprite facing. Drop any
            // contradictory model-authored facing self-report before stamping
            // the actual spherical behavior.
            ...existing.value.roles.filter((role) => !role.startsWith('vfx.facing.')),
            'vfx.facing.camera-spherical',
            ...(existing.value.roles.some((role) => role.startsWith('vfx.effect.surface'))
              ? []
              : ['vfx.effect.surface.card']),
          ],
        };
      }
    }
  }
  if (semanticForExport !== undefined) {
    const semantic = validateSemanticMetadataV1(semanticForExport);
    if (!semantic.valid || !semantic.value) {
      const detail = semantic.issues
        .map((issue) => `${issue.path || '<root>'}: ${issue.message}`)
        .join('; ');
      throw new TypeError(
        `Invalid ${KILN_SEMANTIC_EXTRAS_KEY} on node ${threeObj.name || '<unnamed>'}: ${detail}`,
      );
    }
    extras[KILN_SEMANTIC_EXTRAS_KEY] = cloneSemanticMetadataV1(semantic.value);
  }
  if (Object.keys(extras).length) gtNode.setExtras(extras);

  gtNode.setTranslation([threeObj.position.x, threeObj.position.y, threeObj.position.z]);
  gtNode.setRotation([
    threeObj.quaternion.x,
    threeObj.quaternion.y,
    threeObj.quaternion.z,
    threeObj.quaternion.w,
  ]);
  gtNode.setScale([threeObj.scale.x, threeObj.scale.y, threeObj.scale.z]);
  // Review-loaded GPU instances carry an explicit local matrix, not authored TRS.
  if (!threeObj.matrixAutoUpdate) gtNode.setMatrix(threeObj.matrix.toArray());

  if ((threeObj as { isMesh?: boolean }).isMesh) {
    const threeMesh = threeObj as THREE.Mesh;
    const threeMats = Array.isArray(threeMesh.material) ? threeMesh.material : [threeMesh.material];
    const gtMats = threeMats.map((material) =>
      bridgeMaterial(doc, material, matCache, texCache, authorExtras, atlas),
    );
    const gtMat = Array.isArray(threeMesh.material) ? gtMats : gtMats[0]!;

    // Key the mesh cache by (geometry ref, material ref) so createInstance
    // (same geo + mat as source) produces a GLB-level mesh instance: a
    // single Mesh referenced by multiple Nodes. Cuts duplicated accessors
    // for wheels, bolts, fence posts, etc.
    const cacheKey = `${threeMesh.geometry.uuid}__${threeMats.map((material) => material.uuid).join('_')}`;
    let gtMesh = meshCache.get(cacheKey);
    if (!gtMesh) {
      gtMesh = bridgeGeometry(doc, buf, threeMesh.geometry, gtMat, threeMesh.name || 'mesh', atlas);
      meshCache.set(cacheKey, gtMesh);
    }
    gtNode.setMesh(gtMesh);
  } else if ((threeObj as THREE.Object3D & { isSprite?: boolean }).isSprite) {
    const sprite = threeObj as THREE.Sprite;
    const threeMat = sprite.material;
    const gtMat = bridgeMaterial(doc, threeMat, matCache, texCache, authorExtras, atlas);
    // Unit XY quad matches Three.js Sprite scale semantics. Non-default center
    // and material rotation are baked into the quad; camera-facing remains an
    // explicit semantic runtime behavior on the exported node.
    const centerX = sprite.center?.x ?? 0.5;
    const centerY = sprite.center?.y ?? 0.5;
    const rotation = sprite.material.rotation ?? 0;
    const cacheKey = `kiln-sprite-quad:${centerX}:${centerY}:${rotation}__${threeMat.uuid}`;
    let gtMesh = meshCache.get(cacheKey);
    if (!gtMesh) {
      const geometry = new THREE.PlaneGeometry(1, 1);
      if (centerX !== 0.5 || centerY !== 0.5) {
        geometry.translate(0.5 - centerX, 0.5 - centerY, 0);
      }
      if (rotation !== 0) geometry.rotateZ(rotation);
      gtMesh = bridgeGeometry(doc, buf, geometry, gtMat, sprite.name || 'sprite-quad', atlas);
      meshCache.set(cacheKey, gtMesh);
    }
    gtNode.setMesh(gtMesh);
  }

  if (threeObj.name) {
    nodeMap.set(threeObj.name, gtNode);
  }

  for (const child of threeObj.children) {
    const childNode = bridgeNode(
      doc,
      buf,
      child,
      matCache,
      nodeMap,
      meshCache,
      texCache,
      authorExtras,
      atlas,
    );
    gtNode.addChild(childNode);
  }

  return gtNode;
}

function animationInterpolation(track: THREE.KeyframeTrack): 'LINEAR' | 'STEP' | 'CUBICSPLINE' {
  if (isCubicSplineTrack(track)) return 'CUBICSPLINE';
  const mode = track.getInterpolation();
  if (mode === THREE.InterpolateDiscrete) return 'STEP';
  if (mode === THREE.InterpolateLinear) return 'LINEAR';
  throw new Error(
    `Unsupported animation interpolation on ${track.name}; use LINEAR, STEP or CUBICSPLINE.`,
  );
}

/** A track's values with its final value held to one more key. A cubic-spline key is
 * [in-tangent, value, out-tangent]: the old last key leaves at rest and the held key arrives
 * at rest, so the tail stays still. */
function valuesWithHeldKey(track: THREE.KeyframeTrack): Float32Array {
  const values = Array.from(track.values);
  const tuple = track.getValueSize();
  if (!isCubicSplineTrack(track)) return Float32Array.from([...values, ...values.slice(-tuple)]);
  const size = tuple / 3;
  values.fill(0, values.length - size);
  const rest = new Array<number>(size).fill(0);
  const held = values.slice(values.length - 2 * size, values.length - size);
  return Float32Array.from([...values, ...rest, ...held, ...rest]);
}

/** glTF derives duration from sampler times. Encode a trailing hold so an explicit
 * clip duration survives either exporter, while review extras keep authored keys. */
function clipsWithDurationSamples(clips: THREE.AnimationClip[]): THREE.AnimationClip[] {
  return clips.map((clip) => {
    const end = Math.fround(clip.duration);
    const needsHold = (track: THREE.KeyframeTrack) =>
      track.times.length > 0 && track.times[track.times.length - 1]! < end;
    if (!clip.tracks.some(needsHold)) return clip;
    const copied = clip.clone();
    for (const track of copied.tracks) {
      if (!needsHold(track)) continue;
      const values = valuesWithHeldKey(track);
      track.times = Float32Array.from([...track.times, end]);
      track.values = values;
    }
    return copied;
  });
}

function bridgeAnimations(
  doc: Document,
  buf: GtBuffer,
  clips: THREE.AnimationClip[],
  nodeMap: Map<string, GtNode>,
  warnings: string[],
): void {
  for (const clip of clips) {
    const anim = doc.createAnimation(clip.name);

    for (const track of clip.tracks) {
      const dotIdx = track.name.lastIndexOf('.');
      const nodeName = track.name.substring(0, dotIdx);
      const property = track.name.substring(dotIdx + 1);

      const targetNode = nodeMap.get(nodeName);
      if (!targetNode) {
        warnings.push(`Animation target "${nodeName}" not found - skipped`);
        continue;
      }

      let targetPath: 'translation' | 'rotation' | 'scale';
      let valueType: AccessorTypeStr;
      if (property === 'position') {
        targetPath = 'translation';
        valueType = TYPE_VEC3;
      } else if (property === 'quaternion') {
        targetPath = 'rotation';
        valueType = TYPE_VEC4;
      } else if (property === 'scale') {
        targetPath = 'scale';
        valueType = TYPE_VEC3;
      } else {
        warnings.push(`Unsupported animation property "${property}" on "${nodeName}" - skipped`);
        continue;
      }

      const inputAcc = doc
        .createAccessor(`${clip.name}_${nodeName}_input`)
        .setArray(new Float32Array(track.times))
        .setType(TYPE_SCALAR)
        .setBuffer(buf);

      const outputAcc = doc
        .createAccessor(`${clip.name}_${nodeName}_output`)
        .setArray(new Float32Array(track.values))
        .setType(valueType)
        .setBuffer(buf);

      const sampler = doc
        .createAnimationSampler()
        .setInput(inputAcc)
        .setOutput(outputAcc)
        .setInterpolation(animationInterpolation(track));

      const channel = doc
        .createAnimationChannel()
        .setTargetNode(targetNode)
        .setTargetPath(targetPath)
        .setSampler(sampler);

      anim.addSampler(sampler);
      anim.addChannel(channel);
    }

    // Never serialize an empty Animation object: Khronos correctly reports
    // EMPTY_ENTITY as an error. Advisory-only unresolved tracks are skipped;
    // explicit required tracks have already been blocked by deterministic QA.
    if (anim.listChannels().length === 0) anim.dispose();
  }
}

const REVIEW_CLIPS_EXTRAS_KEY = 'kilnReviewClipsV1';

/** Declared loop intent from createClip({ loop }), exported as animations[].extras. */
function clipLoopIntent(clip: THREE.AnimationClip): 'loop' | 'once' | undefined {
  const intent = (clip.userData as { kilnLoopIntent?: unknown } | undefined)?.kilnLoopIntent;
  return intent === 'loop' || intent === 'once' ? intent : undefined;
}

/** Record loop intent on each exported animation, and report whether every authored
 * track became a native channel. Only then can review read the native animations
 * alone, so the bounded review copy stays out of the artifact. */
function finishNativeAnimations(doc: Document, clips: THREE.AnimationClip[]): boolean {
  const animations = doc.getRoot().listAnimations();
  let complete = true;
  for (const clip of clips) {
    const matches = animations.filter((animation) => animation.getName() === clip.name);
    const animation = matches.length === 1 ? matches[0]! : undefined;
    if (!animation || animation.listChannels().length !== clip.tracks.length) complete = false;
    const intent = clipLoopIntent(clip);
    if (animation && intent)
      animation.setExtras({ ...animation.getExtras(), kilnLoopIntent: intent });
  }
  return complete && animations.length === clips.length;
}
const REVIEW_CLIP_LIMITS = {
  clips: 32,
  tracks: 256,
  samplesPerTrack: 4_096,
  valuesPerTrack: 16_384,
} as const;

/** Preserve the authored review clip vocabulary in artifact bytes, including
 * unresolved tracks that glTF cannot encode as native channels. Review tools
 * use this bounded data only to reconstruct deterministic poses/warnings; it
 * is not executable source and native valid channels remain authoritative to
 * ordinary glTF consumers. Version 2 adds CUBICSPLINE tracks, whose values hold
 * [in-tangent, value, out-tangent] per key as a glTF sampler does; it is written
 * only when a clip has one, so every other copy stays version 1. */
function reviewClipExtras(clips: THREE.AnimationClip[]): Record<string, unknown> {
  if (clips.length > REVIEW_CLIP_LIMITS.clips) {
    throw new Error(`Animation review clip limit exceeded (${REVIEW_CLIP_LIMITS.clips}).`);
  }
  let trackCount = 0;
  return {
    version: clips.some((clip) => clip.tracks.some(isCubicSplineTrack)) ? 2 : 1,
    clips: clips.map((clip) => ({
      name: clip.name,
      duration: clip.duration,
      ...(clipLoopIntent(clip) ? { loopIntent: clipLoopIntent(clip) } : {}),
      tracks: clip.tracks.map((track) => {
        trackCount++;
        if (trackCount > REVIEW_CLIP_LIMITS.tracks) {
          throw new Error(`Animation review track limit exceeded (${REVIEW_CLIP_LIMITS.tracks}).`);
        }
        if (
          track.times.length > REVIEW_CLIP_LIMITS.samplesPerTrack ||
          track.values.length > REVIEW_CLIP_LIMITS.valuesPerTrack
        ) {
          throw new Error('Animation review sample limit exceeded.');
        }
        const times = Array.from(track.times);
        const values = Array.from(track.values);
        if (!times.every(Number.isFinite) || !values.every(Number.isFinite)) {
          throw new Error('Animation review tracks must contain only finite values.');
        }
        return { name: track.name, times, values, interpolation: animationInterpolation(track) };
      }),
    })),
  };
}

// =============================================================================
// Public API
// =============================================================================

export interface RenderResult {
  /** Effective exporter inputs, retained with exact reviewed artifacts for explicit rebuilds. */
  rebuildOptions?: RebuildOptions;
  /** Host requirements receipt; generated metadata cannot establish or replace it. */
  requirements: RequirementsContext;
  /** Optional host cache receipt. This identifies evaluation reuse, not image fidelity. */
  buildCache?: { key: `sha256:${string}`; hit: boolean };
  glb: Buffer;
  /** SHA-256 identity of the exact returned GLB bytes. */
  artifactGlbSha256: `sha256:${string}`;
  tris: number;
  meta: KilnCodeMeta;
  warnings: string[];
  /** Automatic category diagnostics captured from the exact final source scene. */
  diagnosticViews?: CapturedDiagnosticV1[];
  materialMetrics?: MaterialMetricsV1;
  materialRecipeApplications?: MaterialRecipeApplicationProvenanceV1[];
  materialResourceProvenance?: MaterialResourceProvenanceV1[];
  /** Exact host-approved input dependencies, including licenses and procedural recipes.
   * These are declared build inputs, not proof that every supplied map was used. */
  materialLibraryDependencies?: MaterialManifest[];
  /** Textures baked into the returned GLB, including bounded procedural lineage. */
  bakedTextures?: BakedTextureProvenanceV1[];
  integrationManifest: IntegrationManifestV1;
}

/**
 * Bake-time material-consolidation mode (opt-in, default off).
 *   - `off`     — today's output, byte-identical across every consumer.
 *   - `auto`    — grade-aware: runs `palette` only when it would actually act
 *                 (>= PALETTE_MIN distinct materials — i.e. the asset is grade
 *                 C/D/F from material sprawl); below that it is a no-op, byte-
 *                 identical to `off`. The default grade-lift lever for the agent
 *                 path: lean assets stay untouched, sprawling heroes collapse.
 *   - `palette` — merge distinct flat-color materials into one palette material
 *                 + palette texture (`palette → weld → prune`). Node graph,
 *                 named pivots, and animations are fully preserved, so it is safe
 *                 for animated assets + Kiln City behaviors. Lifts the grade by
 *                 collapsing the material count (the grade's primary axis).
 *   - `full`    — `palette` plus rigid-group merging. Animation targets, joints,
 *                 semantic, visibility and LOD boundaries keep their geometry;
 *                 every node keeps its name and hierarchy. Other named meshes
 *                 may become empty or hold a merged group. Shared geometry is
 *                 copied only within the byte budget; merged indices stay 16-bit.
 * A render that omits the mode takes `KILN_BAKE_OPTIMIZE` (else `off`); what every
 * pass keeps intact is listed on {@link consolidateMaterials}.
 */
export type OptimizeMode = 'off' | 'auto' | 'palette' | 'full';

/** What a consolidation pass did (recorded in provenance / render.meta). */
export interface OptimizeSummary {
  /** The mode actually applied (may differ from the request after auto-degrade). */
  mode: 'palette' | 'full';
  materialsBefore: number;
  materialsAfter: number;
  drawsBefore: number;
  drawsAfter: number;
  /** Full-mode boundaries, locks and rejected buckets, before final cleanup. */
  rigidMerge?: RigidMergeSummary;
}

/**
 * GPU-instancing pass mode (M1c — a PERF/filesize lever, NOT a grade lever; the
 * A–F grade keys on material count and is unchanged by instancing):
 *   - `off`  — never run the pass.
 *   - `auto` — run only for `role: 'fill'` assets (high-repetition scatter is
 *              where batching pays; hero/vehicle assets keep their node graph).
 *   - `on`   — always attempt (still skipped for animated/skinned docs and
 *              assets with `Joint_*` pivots — see {@link applyGpuInstancing}).
 */
export type InstanceMode = 'off' | 'auto' | 'on';

/** What a GPU-instancing pass did (recorded in provenance / render.meta). */
export interface InstancingSummary {
  /** Instanced batch nodes created (one per shared mesh). */
  batches: number;
  /** Total node copies folded into those batches. */
  instances: number;
  drawsBefore: number;
  drawsAfter: number;
}

export interface RenderSceneResult {
  indexBuffers: IndexBufferReceipt;
  /** Binary GLB bytes, platform-agnostic (Buffer-compatible in Node). */
  bytes: Uint8Array;
  /** SHA-256 identity of `bytes`. */
  artifactGlbSha256: `sha256:${string}`;
  tris: number;
  warnings: string[];
  /** Official Khronos report for these exact post-transform bytes. */
  gltfValidation: KhronosGltfValidationReport;
  /** Five-signal deterministic report for the exact scene and final bytes. */
  qaReport: AssetRequirementsQaReportV2;
  requirements: RequirementsContext;
  /** Post-dedup (and post-optimize, when enabled) instanceability report
   *  (informational). Undefined if it threw. */
  instanceability?: InstanceabilityReport;
  /** Set if metric computation threw; bytes are still valid. */
  metricsError?: string;
  /** Textures encoded to PNG at export time (T2.2). Absent when none were baked. */
  bakedTextures?: BakedTextureProvenanceV1[];
  /** Set when an opt-in consolidation pass ran (optimize !== 'off'). */
  optimize?: OptimizeSummary;
  /** Set when the GPU-instancing pass created batches (instance !== 'off'). */
  instancing?: InstancingSummary;
  /** Category captures selected only by trusted intent from the exact source scene. */
  diagnosticViews?: CapturedDiagnosticV1[];
  materialMetrics?: MaterialMetricsV1;
  materialRecipeApplications?: MaterialRecipeApplicationProvenanceV1[];
  materialResourceProvenance?: MaterialResourceProvenanceV1[];
  integrationManifest: IntegrationManifestV1;
}

export interface RenderSceneOptions {
  /** Exact full-vertex welding by default; asBuilt skips the index pass. */
  indexPolicy?: IndexPolicy;
  /** Host-only migration option; omitted keeps the established exporter. */
  gltfExporter?: 'legacy' | 'three';
  /** Warn about unsupported custom attributes (default), or reject before export. */
  geometryPolicy?: GeometryExportPolicy;
  /** Name of the glTF scene. Defaults to 'Scene'. */
  sceneName?: string;
  /** Animation clips to bridge into the document. */
  clips?: THREE.AnimationClip[];
  /**
   * Run gltf-transform dedup() before serializing. Default true. Set false
   * to inspect raw bridge output for debugging.
   */
  dedup?: boolean;
  /** Legacy argument accepted only to return an explicit migration-required error. */
  category?: string;
  /** Legacy argument accepted only to return an explicit migration-required error. */
  intent?: AssetIntentV1;
  /** Host established binding; never read from source metadata. */
  requirements?: RequirementsBinding;
  /**
   * Opt-in material consolidation, applied after dedup. Defaults to the
   * `KILN_BAKE_OPTIMIZE` env (else `off`). `off` is byte-identical to today.
   * See {@link OptimizeMode}.
   */
  optimize?: OptimizeMode;
  /**
   * GPU-instancing pass (EXT_mesh_gpu_instancing) for repeated geometry,
   * applied between dedup and optimize (the upstream-canonical order:
   * dedup → instance → palette). Defaults to the `KILN_BAKE_INSTANCE` env
   * (else `auto`, which only acts for `role: 'fill'`). See {@link InstanceMode}.
   */
  instance?: InstanceMode;
  /** Agent-declared asset role — drives the `instance: 'auto'` gate. */
  role?: AssetRole;
  /**
   * Re-serialization of a scene that has already been adjudicated, so asset QA
   * observes rather than blocks.
   *
   * The review tools pose a loaded scene and export it again to get one camera
   * cell out of the render port. That export is not a new asset submission: the
   * bytes it derives from were produced by this engine and passed QA on the way
   * out. Re-adjudicating them fails on facts the round trip destroys rather
   * than on anything wrong with the asset — a texture that arrives back as a
   * decoded image no longer carries the payload provenance
   * `MAT_TEXTURE_DECODE_FAILED` looks for, so every textured asset was rejected
   * by its own animation preview.
   *
   * Reports are still computed and still record their real disposition, so
   * telemetry stays honest; only the throw is withheld. This is deliberately
   * narrower than `KILN_QA_MODE`, which turns blocking off for a whole process.
   */
  derivative?: boolean;
}

function finalTextureForSlot(material: GtMaterial, slot: string): GtTexture | null {
  switch (slot) {
    case 'map':
      return material.getBaseColorTexture();
    case 'normalMap':
      return material.getNormalTexture();
    case 'roughnessMap':
    case 'metalnessMap':
      return material.getMetallicRoughnessTexture();
    case 'emissiveMap':
      return material.getEmissiveTexture();
    case 'aoMap':
      return material.getOcclusionTexture();
    default:
      return null;
  }
}

/**
 * Rebind engine-authored texture lineage to a downstream final GLB.
 *
 * Studio may legally rewrite the first engine export through instancing, ORM
 * packing, and KTX2 transcoding before persistence. The authored recipe and
 * source PNG identity remain useful, but their original artifact hash is not a
 * claim about those final bytes. Resolve each recorded material slot against
 * the final document and attach the exact embedded image and GLB identities.
 * No generated source is executed.
 */
export async function bindBakedTextureProvenanceToFinalGlb(
  baked: readonly BakedTextureProvenanceV1[],
  finalGlb: Uint8Array,
): Promise<BakedTextureProvenanceV1[]> {
  if (baked.length === 0) return [];
  const doc = await engineIO().readBinary(finalGlb);
  const root = doc.getRoot();
  const byMaterialName = new Map<string, GtMaterial[]>();
  for (const material of root.listMaterials()) {
    const name = material.getName() || '(unnamed material)';
    const list = byMaterialName.get(name) ?? [];
    list.push(material);
    byMaterialName.set(name, list);
  }
  const nodesByName = new Map<string, GtNode[]>();
  for (const node of root.listNodes()) {
    const list = nodesByName.get(node.getName()) ?? [];
    list.push(node);
    nodesByName.set(node.getName(), list);
  }
  const artifactGlbSha256 = `sha256:${await sha256Hex(finalGlb)}` as const;

  return baked.flatMap((entry) => {
    const resolved = new Set<GtTexture>();
    for (const binding of entry.bindings) {
      const nodeMaterials = (nodesByName.get(binding.node) ?? []).flatMap(
        (node) =>
          node
            .getMesh()
            ?.listPrimitives()
            .flatMap((primitive) => {
              const material = primitive.getMaterial();
              return material ? [material] : [];
            }) ?? [],
      );
      const materials = nodeMaterials.filter(
        (material) => (material.getName() || '(unnamed material)') === binding.material,
      );
      const candidates = materials.length
        ? materials
        : (byMaterialName.get(binding.material) ?? []);
      for (const material of candidates) {
        const texture = finalTextureForSlot(material, binding.slot);
        if (texture) resolved.add(texture);
      }
    }
    // Texture names survive ordinary transforms and are a safe disambiguator
    // when instancing replaced the authored node. Do not use the name alone if
    // it is empty: unnamed textures are common and not identities.
    if (resolved.size === 0 && entry.texture !== '(unnamed texture)') {
      for (const texture of root.listTextures()) {
        if (texture.getName() === entry.texture) resolved.add(texture);
      }
    }
    if (resolved.size !== 1) return [];
    const texture = [...resolved][0]!;
    const image = texture.getImage();
    const mime = texture.getMimeType();
    if (!image || !mime) return [];
    return [
      {
        ...entry,
        artifactGlbSha256,
        finalMime: mime,
        finalImageSha256: `sha256:${createHash('sha256').update(image).digest('hex')}` as const,
      },
    ];
  });
}

/** Minimum distinct material-value blocks before palette() generates a texture.
 *  Below this it is a no-op (an asset with very few materials is already cheap).
 *  Aligned with the instanceability rubric: grade B tops out at 3 materials, so
 *  the first grade-C count (4) must trigger `auto` consolidation. */
const PALETTE_MIN = 4;

/** Resolve the effective optimize mode: explicit option wins, else the env, else off. */
function resolveOptimize(opt?: OptimizeMode): OptimizeMode {
  if (opt) return opt;
  const env = process.env['KILN_BAKE_OPTIMIZE'];
  return env === 'auto' || env === 'palette' || env === 'full' ? env : 'off';
}

/** Minimum nodes sharing one mesh before the instancing pass batches them.
 *  The gltf-transform default (5) — below that the extension's byte overhead
 *  and loader bookkeeping outweigh the draw savings. */
const INSTANCE_MIN = 5;

/** Resolve the effective instance mode: explicit option wins, else the env, else auto. */
function resolveInstance(opt?: InstanceMode): InstanceMode {
  if (opt) return opt;
  const env = process.env['KILN_BAKE_INSTANCE'];
  return env === 'off' || env === 'auto' || env === 'on' ? env : 'auto';
}

/**
 * Run the opt-in GPU-instancing pass (M1c) on a baked Document, in place.
 *
 * Emits `EXT_mesh_gpu_instancing` batches for meshes referenced by
 * >= {@link INSTANCE_MIN} nodes (colonnades, fence runs, container stacks),
 * cutting draw calls + bytes at city scale. **Perf/filesize only — the A–F
 * grade keys on material count and does not move.** Runs after dedup (which
 * links duplicate meshes so sharing is detectable) and before palette()
 * (the upstream-canonical dedup → instance → palette order; join() skips
 * instanced nodes by design so `full` stays safe). {@link instanceByHandedness} keeps mirrored,
 * sheared and tangent-bearing copies drawing as they did as separate nodes.
 *
 * Skipped (returns undefined) when:
 *   - mode is `off`, or `auto` and the role is not `'fill'`;
 *   - the Document carries animations or skins (the library no-ops on
 *     animated docs; skinned nodes are excluded per-mesh — we skip whole);
 *   - any node is named `Joint*` (city behaviors target pivots by name);
 *   - any node carries an `MSFT_lod` chain (a batch would strip the levels' base node);
 *   - no mesh crosses the threshold (nothing to batch).
 */
async function applyGpuInstancing(
  doc: Document,
  mode: InstanceMode,
  role: AssetRole | undefined,
): Promise<InstancingSummary | undefined> {
  if (mode === 'off') return undefined;
  if (mode === 'auto' && role !== 'fill') return undefined;
  if (instancingBlocker(doc)) return undefined;

  const before = collectGlbMetrics(doc);
  await instanceByHandedness(doc, INSTANCE_MIN);

  const { batches, instances } = countInstanceBatches(doc);
  if (batches === 0) return undefined;

  const after = collectGlbMetrics(doc);
  return { batches, instances, drawsBefore: before.drawCalls, drawsAfter: after.drawCalls };
}

/**
 * Run the opt-in consolidation transforms on a baked Document, in place.
 *
 * `palette` collapses distinct untextured flat-color materials into one palette
 * material + a small palette texture (textured materials pass through untouched);
 * `weld` + `prune` clean up. `full` merges rigid groups, preserving animation,
 * joint, semantic, LOD and visibility boundaries while optimizing their rigid
 * descendants independently. `prune` keeps empty leaf nodes + extras so named pivots that Kiln City
 * behaviors target by name survive, and LOD levels that only a chain references.
 * palette groups by alpha mode, so opaque + the one glass slot stay distinct
 * materials (transparency is never flattened into opaque).
 *
 * Returns what it did; throws are the caller's to handle (the GLB is otherwise
 * valid). Pure w.r.t. inputs other than the mutated Document.
 */
async function consolidateMaterials(
  doc: Document,
  mode: 'palette' | 'full',
  keep: readonly string[] = [],
): Promise<OptimizeSummary> {
  // Transform progress must not corrupt CLI/MCP JSON on stdout. Warnings and
  // errors remain visible on stderr; structured merge diagnostics ride below.
  doc.setLogger(new Logger(Logger.Verbosity.WARN));
  const before = collectGlbMetrics(doc);
  const root = doc.getRoot();

  // palette() groups by shading properties and copies only one material's extras.
  // Keep authored material identities whenever those carry application metadata.
  const steps = root
    .listMaterials()
    .some((material) => Object.keys(material.getExtras()).length > 0)
    ? []
    : [palette({ min: PALETTE_MIN })];
  let merge: RigidMergeSummary | undefined;
  if (mode === 'full')
    steps.push(
      rigidMerge({ keep }, (summary) => {
        merge = summary;
      }),
    );
  // A solid texture can be semantically meaningful in more than one slot (for
  // example the same unnamed bytes used as base color, normal, and packed MR).
  // gltf-transform's default solid-texture pruning folds base/MR pixels into
  // factors but retains the normal binding, corrupting that shared-slot case
  // while remaining validator-clean. Preserve authored textures across every
  // material rebake; palette-generated textures and ordinary dead resources are
  // still cleaned normally.
  steps.push(weld(), prune({ keepLeaves: true, keepExtras: true, keepSolidTextures: true }));

  await doc.transform(...steps);

  const after = collectGlbMetrics(doc);
  return {
    mode,
    materialsBefore: before.uniqueMaterials,
    materialsAfter: after.uniqueMaterials,
    drawsBefore: before.drawCalls,
    drawsAfter: after.drawCalls,
    ...(merge ? { rigidMerge: merge } : {}),
  };
}

/** Surface incomplete full-mode work without flooding compact render output per part. */
function optimizeWarnings(summary: OptimizeSummary): string[] {
  const merge = summary.rigidMerge;
  if (!merge) return [];
  const warnings: string[] = [];
  if (merge.skipped)
    warnings.push(`Rigid merge skipped: ${merge.skipped}; geometry left separate.`);
  if (merge.rejected.length)
    warnings.push(
      `Rigid merge retained ${merge.rejected.length} rejected buckets; first: ${merge.rejected[0]!.error}`,
    );
  if (merge.unmatchedKeep.length)
    warnings.push(
      `Rigid merge did not find ${merge.unmatchedKeep.length} requested boundary names.`,
    );
  return warnings;
}

/**
 * Source-data invariants that precede any operation dereferencing bindings. Reuses the structured
 * QA transport without claiming that the full QA rules ran. Like invalid geometry buffers,
 * malformed skin data cannot be made safe by QA-warn or derivative mode. No automatic weight
 * normalization or rest-pose repair occurs.
 */
function assertSceneSourceIntegrity(
  root: THREE.Object3D,
  requirements: ReturnType<typeof resolveRequirementsContext>,
): void {
  const skinIntegrity = inspectSkinIntegrity(root);
  if (skinIntegrity.findings.length) {
    throw new AssetQaBlockedError(
      createRequirementsQaReport(requirements, {
        findings: skinIntegrity.findings,
        executedRules: [],
        evaluatedDimensions: ['exportIntegrity'],
        metrics: {
          exportIntegrity: {
            skinMeshesChecked: skinIntegrity.meshesChecked,
            skinVerticesChecked: skinIntegrity.verticesChecked,
            skinInspectionTruncated: skinIntegrity.truncated,
          },
        },
      }),
      'scene',
    );
  }
  assertPortableMaterialSides(root);
}

/** The headline counts what a plain loader draws: LOD0 and the parts outside every set. */
function drawnTriangleCount(
  root: THREE.Object3D,
  lodSets: ReturnType<typeof collectLodSets>,
): number {
  let tris = countTriangles(root);
  for (const set of lodSets) for (const level of set.levels.slice(1)) tris -= countTriangles(level);
  const hiddenTris = hiddenTriangles(root, new Set(lodSets.flatMap((set) => set.levels.slice(1))));
  if (hiddenTris > 0 && hiddenTris === tris)
    throw new Error(
      'renderSceneToGLB: every triangle is hidden (visible = false on the root or on every part), so nothing draws. Hide parts inside the asset, not all of it.',
    );
  return tris - hiddenTris;
}

/** Write the scene into a transformed glTF document: everything that decides the bytes. */
async function buildSceneDocument(
  root: THREE.Object3D,
  opts: RenderSceneOptions,
  scene: {
    clips: NonNullable<RenderSceneOptions['clips']>;
    exporter: ReturnType<typeof resolveGltfExporter>;
    indexPolicy: ReturnType<typeof resolveIndexPolicy>;
    lodSets: ReturnType<typeof collectLodSets>;
    tris: number;
    atlas: ReturnType<typeof collectAtlasProvenance>;
    warnings: string[];
  },
) {
  const { clips, exporter, indexPolicy, lodSets, tris, atlas, warnings } = scene;
  const nativeClips = clipsWithDurationSamples(clips);
  // Author userData decided once, so both exporters write the same extras.
  const authorExtras = collectAuthorExtras(root);
  warnings.push(...authorExtras.warnings);
  const doc =
    exporter === 'three'
      ? await communitySceneDocument(
          root,
          nativeClips,
          (await import('./exporter-node')).nodeExportPlatform,
          authorExtras,
          atlas,
        )
      : new Document();
  // `asset.generator` defaults to the serializer's own version string, which put
  // `glTF-Transform v4.4.1` inside every artifact's bytes -- and therefore inside
  // `artifactHash`. Taking 4.5.0 moved all 83 recorded hashes and failed the
  // gallery build, and the ENTIRE difference between the two GLBs was that one
  // string: identical BIN chunk, identical accessor min/max, identical everything
  // else. A dependency's version number is provenance about the tool, not identity
  // of the asset, and it has no business in a hash that claims to name the asset.
  // Kiln's own version deliberately stays out too: it belongs in the provenance
  // record, where changing it does not move artifact bytes.
  doc.getRoot().getAsset().generator = 'Kiln';
  if (exporter === 'legacy') {
    const buf = doc.createBuffer();
    const matCache = new Map<THREE.Material, GtMaterial>();
    const meshCache = new Map<string, GtMesh>();
    const texCache = new Map<THREE.Texture, GtTexture>();
    const nodeMap = new Map<string, GtNode>();

    const rootNode = bridgeNode(
      doc,
      buf,
      root,
      matCache,
      nodeMap,
      meshCache,
      texCache,
      authorExtras,
      atlas,
    );
    const gltfScene = doc.createScene(opts.sceneName ?? 'Scene').addChild(rootNode);
    doc.getRoot().setDefaultScene(gltfScene);

    if (clips.length > 0) {
      const review = reviewClipExtras(clips);
      bridgeAnimations(doc, buf, nativeClips, nodeMap, warnings);
      if (!finishNativeAnimations(doc, nativeClips))
        gltfScene.setExtras({ [REVIEW_CLIPS_EXTRAS_KEY]: review });
    }
  } else {
    const scene = doc.getRoot().getDefaultScene() ?? doc.getRoot().listScenes()[0];
    if (!scene) throw new Error('Community exporter produced no scene.');
    scene.setName(opts.sceneName ?? 'Scene');
    if (clips.length > 0) {
      const review = reviewClipExtras(clips);
      if (!finishNativeAnimations(doc, nativeClips))
        scene.setExtras({ [REVIEW_CLIPS_EXTRAS_KEY]: review });
    }
  }
  if (atlas.table) {
    const scene = doc.getRoot().getDefaultScene()!;
    scene.setExtras({ ...scene.getExtras(), kilnAtlasProvenance: atlas.table });
  }
  // A declared budget travels in the bytes, so a receipt from the GLB alone can measure it.
  if (root.userData[KILN_BUDGET_KEY] !== undefined && opts.derivative !== true) {
    const scene = doc.getRoot().getDefaultScene() ?? doc.getRoot().listScenes()[0]!;
    scene.setExtras({
      ...scene.getExtras(),
      [KILN_BUDGET_KEY]: normalizeBudget(root.userData[KILN_BUDGET_KEY]),
    });
  }
  // A declared palette travels the same way; the receipt judges the written materials.
  if (root.userData[KILN_PALETTE_KEY] !== undefined && opts.derivative !== true) {
    const declared = root.userData[KILN_PALETTE_KEY] as { colors?: unknown; threshold?: unknown };
    const scene = doc.getRoot().getDefaultScene() ?? doc.getRoot().listScenes()[0]!;
    scene.setExtras({
      ...scene.getExtras(),
      [KILN_PALETTE_KEY]: normalizePalette(declared?.colors, { threshold: declared?.threshold }),
    });
  }
  // Visibility flags and LOD chains are written before any pass merges or prunes nodes, so
  // those passes see them and keep them; flags first, while every node is still in place.
  applySurfaceBakeExtras(root, doc);
  applyNodeVisibility(root, doc);
  applyLodChains(root, lodSets, doc);
  const indexBuffers = applyIndexPolicy(doc, indexPolicy);

  // Dedupe accessors/materials/meshes so instanced parts (4 wheels, 10 posts,
  // 12 windows) share a single underlying resource in the GLB. Cuts file
  // size on instancing-heavy assets; no-op on unique-geometry scenes.
  if (opts.dedup !== false) {
    try {
      await doc.transform(dedup());
    } catch (err) {
      warnings.push(`dedup transform failed: ${err instanceof Error ? err.message : String(err)}`);
    }
  }

  // Opt-in GPU-instancing pass (M1c) — dedup → instance → palette is the
  // upstream-canonical order (dedup links duplicate meshes so sharing is
  // detectable; join() skips instanced nodes so `full` stays safe). Perf/bytes
  // only; the grade does not move. Failure is swallowed with a warning.
  let instancing: InstancingSummary | undefined;
  try {
    instancing = await applyGpuInstancing(doc, resolveInstance(opts.instance), opts.role);
  } catch (err) {
    warnings.push(`instance transform failed: ${err instanceof Error ? err.message : String(err)}`);
  }

  // Opt-in material consolidation (default off => byte-identical to today). Runs
  // after dedup so palette() works on the already-merged material set. `auto` is
  // grade-aware: it consolidates only when palette() would actually act
  // (>= PALETTE_MIN materials), so lean assets stay byte-stable. Failure is
  // swallowed with a warning — the dedup'd GLB is still valid.
  const optimizeMode = resolveOptimize(opts.optimize);
  let effectiveOptimize: 'off' | 'palette' | 'full' =
    optimizeMode === 'auto' ? 'off' : optimizeMode;
  if (optimizeMode === 'auto' && collectGlbMetrics(doc, tris).uniqueMaterials >= PALETTE_MIN) {
    effectiveOptimize = 'palette';
  }
  let optimize: OptimizeSummary | undefined;
  if (effectiveOptimize !== 'off') {
    try {
      optimize = await consolidateMaterials(doc, effectiveOptimize);
      warnings.push(...optimizeWarnings(optimize));
    } catch (err) {
      warnings.push(
        `optimize (${effectiveOptimize}) failed: ${err instanceof Error ? err.message : String(err)}`,
      );
    }
  }

  return {
    doc,
    indexBuffers,
    ...(instancing ? { instancing } : {}),
    ...(optimize ? { optimize } : {}),
  };
}

/**
 * Serialize a pre-built Three.js scene graph to a GLB byte stream.
 *
 * This is the shared bridge used by both `renderGLB(code)` (headless, re-
 * executes code) and the in-editor `exportGLB()` (uses the live scene).
 *
 * Works in both Node and browser - uses WebIO, which only touches network
 * APIs on the read side. The write side is pure bytes-in/bytes-out, so the
 * same function serializes identically on either platform. That unifies
 * the two historical paths (Three.js GLTFExporter in the editor vs.
 * gltf-transform bridge headlessly) into one canonical pipeline.
 *
 * Pure function: no file I/O, no globals, no WebGL.
 */
export async function renderSceneToGLB(
  root: THREE.Object3D,
  opts: RenderSceneOptions = {},
): Promise<RenderSceneResult> {
  assertNoLegacyRuntimePolicy(opts);
  const requirements = resolveRequirementsContext(opts.requirements);
  const clips = opts.clips ?? [];
  const indexPolicy = resolveIndexPolicy(opts.indexPolicy);
  if (indexPolicy === 'asBuilt' && resolveOptimize(opts.optimize) !== 'off')
    throw new Error('asBuilt indexPolicy requires optimize off to preserve authored buffers');
  if (opts.geometryPolicy !== undefined && !['warn', 'strict'].includes(opts.geometryPolicy))
    throw new Error('geometryPolicy must be warn or strict');
  const exporter = resolveGltfExporter(opts.gltfExporter);
  assertSceneSourceIntegrity(root, requirements);
  // A set of LOD tiers needs its declared thresholds before anything is written. A
  // derivative re-serializes a review scene that has no declarations, so it is not judged.
  const lodSets = opts.derivative === true ? [] : collectLodSets(root);
  // An opt-in solid assertion is the author's, so a derivative re-serialization is not judged.
  if (opts.derivative !== true) assertRequiredSolids(root);
  const warnings = inspectGeometryExport(root, opts.geometryPolicy, exporter);
  const tris = drawnTriangleCount(root, lodSets);
  const materialRecipeApplications = collectMaterialRecipeApplications(root);
  const materialResourceProvenance = collectMaterialResourceProvenance(root);

  // Runtime-aware joint-name validation (follow-up #6 from the W1.1 spike
  // report). Walk the scene graph + animation tracks and surface any track
  // whose target name doesn't resolve to a scene node. Non-fatal - the GLB
  // still renders; agents iterating on code use these warnings to fix the
  // next iteration. Runs before the bridge so the descriptive "rename the
  // pivot" hint is first; the bridge also emits a briefer "target not
  // found - skipped" for each unresolved track (kept for compatibility).
  for (const w of inspectGeneratedAnimation(root, clips)) warnings.push(w);
  const externalSupport = requirements.requirements.requirements.externalSupport;
  for (const w of inspectSceneStructure(root, {
    ...(externalSupport?.state === 'requested'
      ? { externalSupport: externalSupport.value.supports }
      : {}),
  }))
    warnings.push(w);

  // T2.2 — encode in-memory textures to PNG BEFORE QA, so QA judges the file
  // that will actually be written. A procedural DataTexture used to reach the
  // bridge with no encoded bytes and be dropped without a word; now it is
  // either baked into the GLB or warned about by name.
  const atlas = collectAtlasProvenance(root);
  const bakedTextures = await bakeSceneTextures(root, warnings);
  // A normal-mapped mesh without tangents makes every runtime invent its own
  // tangent basis, so the same asset lights differently in different engines.
  // Only touches meshes that actually carry a normal map — the attribute
  // changes the exported bytes.
  ensureNormalMapTangents(root, warnings);

  const qaPolicy = qaPolicyFromEnv();
  const sceneEvidence = await collectRequirementsSceneEvidence(requirements, root, qaPolicy);
  const sceneQaReport = runRequirementsSceneQa(requirements, root, clips, qaPolicy, sceneEvidence);
  // A derivative export withholds the throw without hiding the finding.
  const qaBlocks = qaBlockingEnabled() && opts.derivative !== true;
  const qaSuppressedBy = opts.derivative === true ? 'derivative re-serialization' : 'KILN_QA_MODE';
  if (sceneQaReport.disposition === 'block') {
    const blocked = new AssetQaBlockedError(sceneQaReport, 'scene');
    if (qaBlocks) throw blocked;
    warnings.push(`${blocked.message} — block suppressed by ${qaSuppressedBy}`);
  }

  const { doc, indexBuffers, instancing, optimize } = await buildSceneDocument(root, opts, {
    clips,
    exporter,
    indexPolicy,
    lodSets,
    tris,
    atlas,
    warnings,
  });

  // Instanceability metrics, measured against the post-dedup() (and post-optimize,
  // when enabled) Document so the counts reflect the GLB the runtime actually
  // loads. Informational only — never a gate. Failure is swallowed: the GLB is
  // still valid without it. Triangle count can change under `full` (join welds
  // primitives), so derive it from the final Document rather than the pre-bake tris.
  let instanceability: InstanceabilityReport | undefined;
  let metricsError: string | undefined;
  try {
    // Derive tris from the Document when a transform reshaped it (join welds
    // primitives; instancing folds N nodes into one batch whose tris the
    // instance-aware counter multiplies back out).
    const metrics: InstanceabilityMetrics = collectGlbMetrics(
      doc,
      optimize || instancing ? undefined : tris,
    );
    instanceability = gradeInstanceability(metrics, {
      mergeCandidates: materialMergeCandidates(doc),
    });
  } catch (err) {
    metricsError = err instanceof Error ? err.message : String(err);
  }

  let materialMetrics: MaterialMetricsV1 | undefined;
  let materialAdvice: MaterialAdviceV1[] = [];
  try {
    materialMetrics = collectMaterialMetricsV1(doc);
    // A declared material limit is measured in the budget receipt instead of these notes.
    const declaration = readBudgetDeclaration(
      (doc.getRoot().getDefaultScene()?.getExtras() as Record<string, unknown> | undefined)?.[
        KILN_BUDGET_KEY
      ],
    );
    if (!declaresMaterialLimits(declaration))
      materialAdvice = adviseMaterialsV1(materialMetrics, DEFAULT_MATERIAL_REFERENCE);
  } catch (error) {
    warnings.push(
      `material metrics failed: ${error instanceof Error ? error.message : String(error)}`,
    );
  }

  const io = engineIO();
  ensureDefaultScene(doc);
  await refreshAtlasDocumentProvenance(doc);
  await validateAtlasDocumentProvenance(doc);
  const bytes = await io.writeBinary(doc);
  const artifactGlbSha256 = `sha256:${await sha256Hex(bytes)}` as const;
  const boundBakedTextures = bakedTextures.map((entry) => ({
    ...entry,
    artifactGlbSha256,
  }));
  const gltfValidation = await validateFinalGlbBytes(bytes);
  const qaReport = await appendRequirementsFinalQa(
    requirements,
    sceneQaReport,
    gltfValidation,
    bytes,
    instanceability,
    metricsError,
    materialMetrics,
    materialAdvice,
  );
  if (qaReport.disposition === 'block') {
    const blocked = new AssetQaBlockedError(qaReport, 'final-glb', gltfValidation);
    if (qaBlocks) throw blocked;
    warnings.push(`${blocked.message} — block suppressed by ${qaSuppressedBy}`);
  }
  for (const issue of gltfValidation.issues.messages) {
    if (issue.severity !== 1) continue;
    warnings.push(
      `glTF ${issue.code}${issue.pointer ? ` at ${issue.pointer}` : ''}: ${issue.message}`,
    );
  }

  const integrationManifest = await inspectGlbIntegration(bytes, {
    ...(opts.role ? { requestedRole: opts.role } : {}),
    validation: gltfValidation,
  });
  if (!integrationManifest) throw new Error('renderSceneToGLB: final GLB has no measurable scene');
  // Delivery findings are advisory: each is a build warning, never a QA disposition.
  for (const finding of integrationManifest.deliveryDiagnostics ?? [])
    warnings.push(`${finding.code} ${finding.path}: ${finding.message}`);
  const palette = integrationManifest.palette;
  for (const finding of palette?.offPalette ?? [])
    warnings.push(
      `PALETTE_OFF material ${JSON.stringify(finding.material)} ${finding.color} is delta E ${finding.deltaE} from the nearest palette entry ${finding.nearest} (threshold ${palette!.threshold})${finding.textured ? '; the factor tints a texture that is not judged' : ''}.`,
    );

  const diagnosticViews: CapturedDiagnosticV1[] = [];
  const rig = requirements.requirements.requirements.rig;
  // Category diagnostics inspect source semantics/rigs, but show the same default level
  // as the exported scene. Detach alternates so bounds and semantic scans exclude them,
  // then restore exact sibling order even if a capture fails.
  const diagnosticParents = new Map(lodSets.map(({ parent }) => [parent, [...parent.children]]));
  for (const { parent, levels } of lodSets)
    for (const level of levels.slice(1)) parent.remove(level);
  try {
    if (rig?.state === 'requested') {
      const { captureCharacterDiagnosticViews } = await import('./views/character-capture');
      diagnosticViews.push(
        ...(await captureCharacterDiagnosticViews(
          root,
          clips as readonly DuckClip[],
          rig.value,
          Object.values(qaReport.dimensions).flatMap((d) => d.findings),
        )),
      );
    }
    if (requirements.requirements.requirements.mobility?.state === 'requested') {
      const { captureVehicleDiagnosticViews } = await import('./views');
      diagnosticViews.push(...captureVehicleDiagnosticViews(root));
    }
  } finally {
    for (const [parent, children] of diagnosticParents) {
      parent.clear();
      parent.add(...children);
    }
  }

  return {
    bytes,
    indexBuffers,
    requirements,
    artifactGlbSha256,
    tris,
    warnings,
    gltfValidation,
    qaReport,
    instanceability,
    metricsError,
    ...(optimize ? { optimize } : {}),
    ...(instancing ? { instancing } : {}),
    ...(materialMetrics ? { materialMetrics } : {}),
    ...(materialRecipeApplications.length ? { materialRecipeApplications } : {}),
    ...(materialResourceProvenance.length ? { materialResourceProvenance } : {}),
    ...(boundBakedTextures.length ? { bakedTextures: boundBakedTextures } : {}),
    integrationManifest,
    ...(diagnosticViews.length ? { diagnosticViews } : {}),
  };
}

/**
 * The bytes of a review derivative and nothing else: the same bytes `renderSceneToGLB` writes with
 * `derivative: true`, without the QA, validator, metrics and manifest evidence a view cell would
 * discard. The scene was already adjudicated when its artifact was built; the source invariants
 * that make a scene unsafe to serialize still throw.
 */
export async function renderReviewDerivativeGlb(
  root: THREE.Object3D,
  opts: Pick<RenderSceneOptions, 'gltfExporter'> = {},
): Promise<Uint8Array> {
  assertSceneSourceIntegrity(root, resolveRequirementsContext(undefined));
  const tris = drawnTriangleCount(root, []);
  if (tris <= 0) throw new Error('renderSceneToGLB: final GLB has no measurable scene');
  // Warnings are evidence about the source, reported when the artifact was built.
  const warnings: string[] = [];
  const atlas = collectAtlasProvenance(root);
  await bakeSceneTextures(root, warnings);
  ensureNormalMapTangents(root, warnings);
  const { doc } = await buildSceneDocument(
    root,
    { ...opts, derivative: true },
    {
      clips: [],
      exporter: resolveGltfExporter(opts.gltfExporter),
      indexPolicy: resolveIndexPolicy(undefined),
      lodSets: [],
      tris,
      atlas,
      warnings,
    },
  );
  ensureDefaultScene(doc);
  await refreshAtlasDocumentProvenance(doc);
  await validateAtlasDocumentProvenance(doc);
  return engineIO().writeBinary(doc);
}

/**
 * Execute Kiln code and serialize to a GLB Buffer.
 *
 * This is the main headless entry point. Takes the JS code Claude produces
 * (the same string shape `/api/kiln/generate` returns) and returns ready-
 * to-write bytes.
 *
 * Pure function: no file I/O, no globals, no WebGL.
 */
export interface RenderGlbOptions {
  indexPolicy?: IndexPolicy;
  requirements?: RequirementsBinding;
  /** Host-only migration option, transported explicitly to isolated workers. */
  gltfExporter?: 'legacy' | 'three';
  geometryPolicy?: GeometryExportPolicy;
  optimize?: OptimizeMode;
  instance?: InstanceMode;
  intent?: AssetIntentV1;
  category?: AssetCategory;
  /** Trusted evaluator dependency; never derived from generated code. */
  textureResolver?: TextureResolver;
  /** Host-approved portable material maps, transported as data to evaluator workers. */
  materialResources?: MaterialLibraryPayload;
  /** In-process host diagnostic sink; not serializable to evaluator workers. */
  diagnosticConsole?: DiagnosticConsole;
}

/**
 * Trusted in-process execute/export implementation.
 *
 * Hosts should normally call {@link renderGLB}. The subprocess evaluator calls
 * this function directly to prevent recursive process creation.
 */
export async function renderGLBInProcess(
  code: string,
  opts: RenderGlbOptions = {},
): Promise<RenderResult> {
  assertNoLegacyRuntimePolicy(opts);
  const requirements = resolveRequirementsContext(opts.requirements);
  if (opts.geometryPolicy !== undefined && !['warn', 'strict'].includes(opts.geometryPolicy))
    throw new Error('geometryPolicy must be warn or strict');
  let textureResolver = opts.textureResolver ?? DEFAULT_TEXTURE_RESOLVER;
  const rebuildOptions: RebuildOptions = {
    indexPolicy: resolveIndexPolicy(opts.indexPolicy),
    gltfExporter: resolveGltfExporter(opts.gltfExporter),
    geometryPolicy: opts.geometryPolicy ?? 'warn',
    optimize: resolveOptimize(opts.optimize),
    ...(resolveOptimize(opts.optimize) === 'full'
      ? { optimizationPipeline: FULL_OPTIMIZATION_PIPELINE }
      : {}),
    instance: resolveInstance(opts.instance),
  };
  let materialLibraryDependencies: MaterialManifest[] | undefined;
  if (opts.materialResources) {
    const { decodeMaterialLibraryPayload, createMaterialLibraryTextureResolver } = await import(
      './material-library-node'
    );
    const materialRecords = await decodeMaterialLibraryPayload(opts.materialResources);
    materialLibraryDependencies = materialRecords.map((record) => structuredClone(record.manifest));
    textureResolver = await createMaterialLibraryTextureResolver(materialRecords, textureResolver);
  }
  const { meta, root, clips, primitiveUsage } = await executeKilnCode(code, {
    textureResolver,
    console: opts.diagnosticConsole,
  });
  const scene = await renderSceneToGLB(root, {
    ...rebuildOptions,
    sceneName: meta.name || 'Scene',
    clips,
    requirements: requirements.binding,
    role: meta.role,
  });

  const {
    category: modelCategory,
    requirements: _requirements,
    intent: _intent,
    policyHash: _policyHash,
    adviceHash: _adviceHash,
    binding: _binding,
    ...modelMeta
  } = meta;
  return {
    glb: Buffer.from(scene.bytes),
    rebuildOptions,
    ...(materialLibraryDependencies ? { materialLibraryDependencies } : {}),
    requirements: scene.requirements,
    artifactGlbSha256: scene.artifactGlbSha256,
    tris: scene.tris,
    meta: {
      ...modelMeta,
      indexBuffers: scene.indexBuffers,
      ...(modelCategory !== undefined ? { modelCategory } : {}),
      tris: scene.tris,
      primitiveUsage,
      ...(scene.instanceability
        ? { instanceability: scene.instanceability, tier: scene.instanceability.grade }
        : {}),
      ...(scene.metricsError ? { metricsError: scene.metricsError } : {}),
      ...(scene.optimize ? { optimize: scene.optimize } : {}),
      ...(scene.instancing ? { instancing: scene.instancing } : {}),
      gltfValidation: scene.gltfValidation,
      qaReport: scene.qaReport,
    },
    warnings: scene.warnings,
    ...(scene.diagnosticViews ? { diagnosticViews: scene.diagnosticViews } : {}),
    ...(scene.materialMetrics ? { materialMetrics: scene.materialMetrics } : {}),
    ...(scene.materialRecipeApplications
      ? { materialRecipeApplications: scene.materialRecipeApplications }
      : {}),
    ...(scene.materialResourceProvenance
      ? { materialResourceProvenance: scene.materialResourceProvenance }
      : {}),
    ...(scene.bakedTextures ? { bakedTextures: scene.bakedTextures } : {}),
    integrationManifest: scene.integrationManifest,
  };
}

export type EvaluatorMode = 'in-process' | 'subprocess' | 'isolated';

/** Resolve the trusted host evaluator flag. Unknown values fail closed. */
export function resolveEvaluatorMode(
  env: Record<string, string | undefined> = process.env,
): EvaluatorMode {
  const value = env['KILN_EVALUATOR_MODE'];
  if (value === undefined || value === '' || value === 'in-process') return 'in-process';
  if (value === 'subprocess') return 'subprocess';
  if (value === 'isolated') return 'isolated';
  throw new Error('Invalid KILN_EVALUATOR_MODE.');
}

/**
 * Execute Kiln code and serialize it to GLB.
 *
 * Subprocess containment is disabled by default and selected only by the
 * trusted host flag. A subprocess error is terminal; this boundary never
 * falls back to unsafe in-process execution.
 */
export async function renderGLB(code: string, opts: RenderGlbOptions = {}): Promise<RenderResult> {
  const mode = resolveEvaluatorMode();
  const exporter = resolveGltfExporter(opts.gltfExporter);
  if (exporter === 'three') opts = { ...opts, gltfExporter: exporter };
  if (mode === 'in-process') return renderGLBInProcess(code, opts);
  if (mode === 'subprocess') {
    const { renderGLBViaSubprocess } = await import('./evaluator/subprocess');
    return renderGLBViaSubprocess(code, opts);
  }
  const { renderGLBViaIsolatedEvaluator } = await import('./evaluator/isolation');
  return renderGLBViaIsolatedEvaluator(code, opts);
}

/**
 * Grade instanceability directly from baked GLB bytes.
 *
 * Used by consumers that hold a finished GLB but not its THREE scene — e.g.
 * Kiln Studio computing the grade web-side from the persisted artifact, so the
 * AgentCore runtime never has to (no wire bump, no runtime image rebuild). Pure
 * read: parses the GLB, walks the post-dedup document, grades. Never throws on a
 * valid GLB; returns undefined if the bytes can't be parsed.
 */
export async function gradeGlbBytes(
  bytes: Uint8Array,
  opts: { category?: string } = {},
): Promise<InstanceabilityReport | undefined> {
  try {
    const doc = await engineIO().readBinary(bytes);
    return gradeInstanceability(collectGlbMetrics(doc), {
      ...opts,
      mergeCandidates: materialMergeCandidates(doc),
    });
  } catch {
    return undefined;
  }
}

/** Result of {@link optimizeGlbBytes}: the consolidated GLB + its re-graded report. */
export interface OptimizeGlbResult {
  /** The consolidated GLB bytes. */
  bytes: Uint8Array;
  /** Instanceability report recomputed on the optimized bytes. */
  report?: InstanceabilityReport;
  /** What the consolidation pass did (absent when only instancing applied). */
  summary?: OptimizeSummary;
  /** What the GPU-instancing pass did (absent when it was off / skipped / no-op). */
  instancing?: InstancingSummary;
  /** Official Khronos report for the exact rebaked bytes. */
  gltfValidation: KhronosGltfValidationReport;
  /** Nonfatal optimization diagnostics; exact bucket details are in summary.rigidMerge. */
  warnings?: string[];
}

/**
 * Consolidate materials in a finished GLB, working from bytes — the web-side
 * counterpart to {@link renderGLB}'s bake-time `optimize` option.
 *
 * Used by Kiln Studio: the AgentCore runtime returns an un-optimized GLB, and the
 * web tier re-bakes it here before persisting, so consolidation reaches prod with
 * NO wire bump / runtime change (the runtime never sees an `optimize` flag). Same
 * `consolidateMaterials` pass + re-grade as the render path. Pure read+write:
 * parses the GLB, transforms, re-serializes; returns `undefined` if the bytes
 * can't be parsed or the transform throws (caller keeps the original GLB).
 */
export async function optimizeGlbBytes(
  bytes: Uint8Array,
  opts: { mode?: OptimizeMode; category?: string; instance?: InstanceMode; role?: AssetRole } = {},
): Promise<OptimizeGlbResult | undefined> {
  const requested = opts.mode ?? 'palette';
  try {
    const io = engineIO();
    const doc = await io.readBinary(bytes);
    await validateAtlasDocumentProvenance(doc);
    // GPU-instancing first (dedup already ran at bake; instance → palette is the
    // canonical order). Defaults OFF here — this is the web-tier re-bake seam, and
    // the caller opts in per-asset (Studio passes instance:'auto' + the record's
    // role, so only fill assets are batched — same gate as the render path).
    let instancing: InstancingSummary | undefined;
    if (opts.instance && opts.instance !== 'off') {
      instancing = await applyGpuInstancing(doc, opts.instance, opts.role);
    }
    // `auto` is grade-aware: consolidate only when palette() would act
    // (>= PALETTE_MIN materials); a no-op auto (or an explicit `off`) keeps
    // the original bytes unchanged — unless instancing acted, in which case
    // the instanced bytes are still worth persisting.
    let summary: OptimizeSummary | undefined;
    let mode: 'palette' | 'full' | undefined;
    if (requested !== 'off') {
      if (requested === 'auto') {
        if (collectGlbMetrics(doc).uniqueMaterials >= PALETTE_MIN) mode = 'palette';
      } else {
        mode = requested;
      }
    }
    if (mode) summary = await consolidateMaterials(doc, mode);
    if (!summary && !instancing) return undefined;
    ensureDefaultScene(doc);
    await refreshAtlasDocumentProvenance(doc);
    await validateAtlasDocumentProvenance(doc);
    const outBytes = await io.writeBinary(doc);
    const gltfValidation = await assertFinalGlbValid(outBytes);
    let report: InstanceabilityReport | undefined;
    try {
      report = gradeInstanceability(collectGlbMetrics(doc), {
        category: opts.category,
        mergeCandidates: materialMergeCandidates(doc),
      });
    } catch {
      report = undefined;
    }
    return {
      bytes: outBytes,
      gltfValidation,
      ...(report ? { report } : {}),
      ...(summary ? { summary } : {}),
      ...(summary ? { warnings: optimizeWarnings(summary) } : {}),
      ...(instancing ? { instancing } : {}),
    };
  } catch (error) {
    if (error instanceof GltfValidationError) throw error;
    return undefined;
  }
}

export interface PackKitResult {
  bytes: Uint8Array;
  summary: KitPackSummary;
  gltfValidation: KhronosGltfValidationReport;
}

/**
 * Apply the kit contract to a finished GLB, working from bytes.
 *
 * Sibling of {@link optimizeGlbBytes} and deliberately the same shape: parse,
 * transform, re-serialise, re-validate against Khronos. The runtime never sees
 * a kit flag, so this reaches production with no wire bump.
 *
 * Returns `undefined` when nothing changed or the bytes cannot be parsed, so a
 * caller keeps the original GLB rather than persisting a no-op rewrite.
 * Khronos validation failures are the one thing that throws: bytes that do not
 * validate must never be persisted, and silently returning the original would
 * hide that this pass produced an invalid file.
 */
export async function packKitGlb(
  bytes: Uint8Array,
  opts: KitPackOptions = {},
): Promise<PackKitResult | undefined> {
  let doc: Document;
  try {
    doc = await engineIO().readBinary(bytes);
  } catch {
    return undefined;
  }

  const summary = await applyKitContract(doc, opts);
  const changed = summary.ormPacked > 0 || summary.variantsAdded.length > 0 || summary.ktx2.applied;
  if (!changed) return undefined;

  ensureDefaultScene(doc);
  const outBytes = await engineIO().writeBinary(doc);
  const gltfValidation = await assertFinalGlbValid(outBytes);
  return { bytes: outBytes, summary, gltfValidation };
}

// =============================================================================
// Palette snap (scene palettes) — web-side hard snap to a user-defined palette
// =============================================================================

/** Result of {@link snapGlbToPalette}. */
export interface SnapGlbResult {
  /** The snapped + consolidated GLB bytes. */
  bytes: Uint8Array;
  /** Instanceability report recomputed on the snapped bytes. */
  report?: InstanceabilityReport;
  /** What the consolidation pass did. */
  summary: OptimizeSummary;
  /** Materials whose color was rewritten to a slot. */
  snapped: number;
  /** Materials left unchanged (textured / hero, or no eligible slot). */
  skipped: number;
  /** Official Khronos report for the exact palette-rebaked bytes. */
  gltfValidation: KhronosGltfValidationReport;
}

/**
 * Hard-snap a finished GLB's materials to a user-defined palette — the bake-time,
 * persisted counterpart of the Kiln City frontend snap. Each flat-color material's
 * base color is rewritten to the perceptually-nearest slot (OKLab, via
 * {@link chooseSlot}) and its PBR set from that slot, so a whole batch generated
 * against one palette lands on exactly those colors and collapses (after
 * `consolidateMaterials`) to ~one material per slot — "reads as one place" + a few
 * draws. Textured / hero materials are left untouched (they carry their own color).
 *
 * Pure read+write (parses GLB, rewrites, re-serializes); returns `undefined` if the
 * bytes can't be parsed or the transform throws (caller keeps the original GLB),
 * mirroring {@link optimizeGlbBytes}.
 */
export async function snapGlbToPalette(
  bytes: Uint8Array,
  slots: readonly SnapPaletteSlot[],
  opts: { category?: string } = {},
): Promise<SnapGlbResult | undefined> {
  if (slots.length === 0) return undefined;
  try {
    const io = engineIO();
    const doc = await io.readBinary(bytes);
    await validateAtlasDocumentProvenance(doc);
    const before = collectGlbMetrics(doc);
    const idx = buildSlotIndex(slots as readonly SnapSlot[]);
    let snapped = 0;
    let skipped = 0;
    for (const mat of doc.getRoot().listMaterials()) {
      // Hero exception — never recolor a textured material (it carries its own color).
      if (mat.getBaseColorTexture()) {
        skipped++;
        continue;
      }
      const base = mat.getBaseColorFactor();
      const emissive = mat.getEmissiveFactor();
      const transparent = mat.getAlphaMode() === 'BLEND' || mat.getAlpha() < 0.98;
      const slotI = chooseSlot(idx, {
        baseLinear: [base[0], base[1], base[2]],
        emissiveLinear: [emissive[0], emissive[1], emissive[2]],
        transparent,
      });
      if (slotI === undefined) {
        skipped++;
        continue;
      }
      const slot = slots[slotI]!;
      const kind = slot.kind ?? 'opaque';
      const [lr, lg, lb] = hexToLinearRgb(slot.color);
      const alpha = kind === 'glass' ? (slot.opacity ?? 0.4) : 1;
      mat.setBaseColorFactor([lr, lg, lb, alpha]);
      mat.setMetallicFactor(slot.metalness ?? 0);
      mat.setRoughnessFactor(slot.roughness ?? (kind === 'glass' ? 0.1 : 0.85));
      if (kind === 'glass') mat.setAlphaMode('BLEND');
      else if (mat.getAlphaMode() === 'BLEND') mat.setAlphaMode('OPAQUE');
      // Glow keeps a "lit" look by emitting its slot color; clear stray emissive otherwise.
      // The slot color is the whole emission, so an authored strength must not scale it.
      mat.setEmissiveFactor(kind === 'glow' ? [lr, lg, lb] : [0, 0, 0]);
      mat.setExtension('KHR_materials_emissive_strength', null);
      snapped++;
    }
    // Snapping made many materials value-identical — dedup merges those objects first
    // (palette() alone keeps distinct objects), then consolidate collapses further.
    await doc.transform(dedup());
    await consolidateMaterials(doc, 'palette');
    // Summary spans the WHOLE snap (original → final), not just the consolidation sub-step,
    // so provenance shows the true material collapse (e.g. 14 → 4).
    const after = collectGlbMetrics(doc);
    const summary: OptimizeSummary = {
      mode: 'palette',
      materialsBefore: before.uniqueMaterials,
      materialsAfter: after.uniqueMaterials,
      drawsBefore: before.drawCalls,
      drawsAfter: after.drawCalls,
    };
    ensureDefaultScene(doc);
    await refreshAtlasDocumentProvenance(doc);
    await validateAtlasDocumentProvenance(doc);
    const outBytes = await io.writeBinary(doc);
    const gltfValidation = await assertFinalGlbValid(outBytes);
    let report: InstanceabilityReport | undefined;
    try {
      report = gradeInstanceability(after, {
        category: opts.category,
        mergeCandidates: materialMergeCandidates(doc),
      });
    } catch {
      report = undefined;
    }
    return {
      bytes: outBytes,
      ...(report ? { report } : {}),
      summary,
      snapped,
      skipped,
      gltfValidation,
    };
  } catch (error) {
    if (error instanceof GltfValidationError) throw error;
    return undefined;
  }
}

// =============================================================================
// Scene composition — merge N placed GLBs into one scene GLB (export)
// =============================================================================

/** One placed asset to compose into the scene: its GLB bytes + a world transform. */
export interface SceneComposePart {
  bytes: Uint8Array;
  transform: {
    /** World position [x, y, z], engine frame (+X fwd, +Y up, ground Y=0), meters. */
    pos: [number, number, number];
    /** Euler rotation in DEGREES, XYZ order (the Kiln/Placement convention). */
    rotDeg: [number, number, number];
    /** Per-axis scale. */
    scale: [number, number, number];
  };
  /** Wrapper node name (e.g. an instanceId) — a debug aid in the exported file. */
  name?: string;
}

export interface SceneComposeOptions {
  /** glTF scene name. Default 'Scene'. */
  sceneName?: string;
  /** Material consolidation across the merged scene. Default 'palette' (a few draws). */
  optimize?: OptimizeMode;
  /** Keep each asset's animation clips. Default false (static dressing). */
  keepAnimations?: boolean;
  /** Retained clip names: preserve source names (default), or disambiguate by placement and clip index. */
  animationNaming?: 'preserve' | 'instance';
}

export interface SceneComposeResult {
  /** The composed scene GLB bytes. */
  bytes: Uint8Array;
  tris: number;
  /** Draw calls in the composed scene (post-optimize). */
  draws: number;
  /** Distinct materials in the composed scene (post-optimize). */
  materials: number;
  /** Per-part skip notes + transform warnings (never throws on one bad part). */
  warnings: string[];
  /** Official Khronos report for the exact composed bytes. */
  gltfValidation: KhronosGltfValidationReport;
  /** Consolidation and rigid-boundary diagnostics when an optimization pass ran. */
  optimize?: OptimizeSummary;
}

/** Euler degrees (XYZ) → a glTF quaternion [x, y, z, w] via THREE (the viewer's frame). */
function eulerDegToQuat(deg: [number, number, number]): [number, number, number, number] {
  const e = new THREE.Euler(
    THREE.MathUtils.degToRad(deg[0]),
    THREE.MathUtils.degToRad(deg[1]),
    THREE.MathUtils.degToRad(deg[2]),
    'XYZ',
  );
  const q = new THREE.Quaternion().setFromEuler(e);
  return [q.x, q.y, q.z, q.w];
}

/**
 * Compose N placed GLBs into a single scene GLB — the Scenes-page export primitive.
 *
 * Pure gltf-transform (no THREE GLTFLoader, whose texture path is browser-DOM-bound):
 * each part's bytes are read into a Document, `mergeDocuments` copies its graph into a
 * master Document (textures copied as bytes, lossless), and its scene roots are
 * reparented under a fresh transform node carrying the placement's TRS. One merge per
 * placement (a Node can't have two parents); a final `dedup()` collapses repeated
 * blueprints (e.g. 30 identical fence posts) and `consolidateMaterials` keeps the
 * export to a few draws. A corrupt/unreadable part becomes a warning and is skipped,
 * never failing the whole export.
 *
 * Runs under Bun in the web tier (same WebIO read→transform→write path as
 * {@link optimizeGlbBytes}). Pure: no fs / globals / WebGL.
 */
export async function composeSceneGLB(
  parts: readonly SceneComposePart[],
  opts: SceneComposeOptions = {},
): Promise<SceneComposeResult> {
  const warnings: string[] = [];
  // engineIO so a part that carries EXT_mesh_gpu_instancing keeps its batches
  // through the merge (mergeDocuments copies the extension onto the master).
  const io = engineIO();
  const master = new Document();
  const masterScene = master.createScene(opts.sceneName ?? 'Scene');
  master.getRoot().setDefaultScene(masterScene);
  let composed = 0;
  const placementNames: string[] = [];

  for (let i = 0; i < parts.length; i++) {
    const part = parts[i]!;
    try {
      const src = await io.readBinary(part.bytes);
      await mergeAtlasDocumentProvenance(master, src);
      if (opts.keepAnimations && opts.animationNaming === 'instance') {
        for (const [clipIndex, animation] of src.getRoot().listAnimations().entries()) {
          animation.setName(
            `${i}:${part.name ?? 'part'}/${clipIndex}:${animation.getName() || 'clip'}`,
          );
        }
      }
      const srcScene = src.getRoot().listScenes()[0];
      const map = mergeDocuments(master, src);
      const wrap = master
        .createNode(part.name ?? `part_${i}`)
        .setTranslation([part.transform.pos[0], part.transform.pos[1], part.transform.pos[2]])
        .setRotation(eulerDegToQuat(part.transform.rotDeg))
        .setScale([part.transform.scale[0], part.transform.scale[1], part.transform.scale[2]]);
      const mergedScene = srcScene ? (map.get(srcScene) as GtScene | undefined) : undefined;
      if (mergedScene) {
        for (const child of mergedScene.listChildren()) wrap.addChild(child);
        mergedScene.dispose();
      }
      masterScene.addChild(wrap);
      placementNames.push(wrap.getName());
      composed++;
    } catch (err) {
      warnings.push(
        `part ${i} (${part.name ?? ''}) skipped: ${err instanceof Error ? err.message : String(err)}`,
      );
    }
  }

  if (composed === 0) throw new Error('composeSceneGLB: no parts could be merged');

  // Static dressing has no shared timeline — drop per-asset clips unless asked to keep.
  if (!opts.keepAnimations) {
    for (const anim of master.getRoot().listAnimations()) anim.dispose();
  }

  try {
    await master.transform(dedup());
  } catch (err) {
    warnings.push(`dedup failed: ${err instanceof Error ? err.message : String(err)}`);
  }

  const optimizeMode: OptimizeMode = opts.optimize ?? 'palette';
  let effectiveOptimize: 'off' | 'palette' | 'full' =
    optimizeMode === 'auto' ? 'off' : optimizeMode;
  if (optimizeMode === 'auto' && collectGlbMetrics(master).uniqueMaterials >= PALETTE_MIN) {
    effectiveOptimize = 'palette';
  }
  let optimize: OptimizeSummary | undefined;
  if (effectiveOptimize !== 'off') {
    try {
      optimize = await consolidateMaterials(master, effectiveOptimize, placementNames);
      warnings.push(...optimizeWarnings(optimize));
    } catch (err) {
      warnings.push(
        `optimize (${effectiveOptimize}) failed: ${err instanceof Error ? err.message : String(err)}`,
      );
    }
  }

  // mergeDocuments brings each source's Buffer across, but a GLB allows ≤1 buffer.
  // Reassign every accessor to the first buffer and drop the rest.
  const rootBuffers = master.getRoot().listBuffers();
  if (rootBuffers.length > 1) {
    const main = rootBuffers[0]!;
    for (const acc of master.getRoot().listAccessors()) acc.setBuffer(main);
    for (let i = 1; i < rootBuffers.length; i++) rootBuffers[i]!.dispose();
  }

  const metrics = collectGlbMetrics(master);
  ensureDefaultScene(master);
  await refreshAtlasDocumentProvenance(master);
  await validateAtlasDocumentProvenance(master);
  const bytes = await io.writeBinary(master);
  const gltfValidation = await assertFinalGlbValid(bytes, 'scene.glb');
  for (const issue of gltfValidation.issues.messages) {
    if (issue.severity !== 1) continue;
    warnings.push(
      `glTF ${issue.code}${issue.pointer ? ` at ${issue.pointer}` : ''}: ${issue.message}`,
    );
  }
  return {
    bytes,
    tris: metrics.triangles,
    draws: metrics.drawCalls,
    materials: metrics.uniqueMaterials,
    warnings,
    gltfValidation,
    ...(optimize ? { optimize } : {}),
  };
}

// =============================================================================
// Runtime-aware animation inspection
// =============================================================================

/**
 * Walk a Kiln-executed scene graph and its animation clips, and surface any
 * track whose target (e.g. `Joint_LeftWheel.rotation`) doesn't resolve to a
 * named node in the scene. These are *warnings*, not errors — the GLB still
 * renders fine, the track just does nothing. Agents iterating on generated
 * code use this signal to pick a real joint name on the next pass.
 *
 * Pure, side-effect free, safe to call without rendering.
 */
export function inspectGeneratedAnimation(
  root: THREE.Object3D,
  clips: THREE.AnimationClip[],
): string[] {
  const warnings: string[] = [];
  if (clips.length === 0) return warnings;

  const nodeNames = new Set<string>();
  root.traverse((obj) => {
    if (obj.name) nodeNames.add(obj.name);
  });

  for (const clip of clips) {
    for (const track of clip.tracks) {
      const dotIdx = track.name.lastIndexOf('.');
      if (dotIdx === -1) {
        warnings.push(`Track "${track.name}" is missing a node.property separator`);
        continue;
      }
      const nodeName = track.name.substring(0, dotIdx);
      const property = track.name.substring(dotIdx + 1);

      if (!nodeNames.has(nodeName)) {
        warnings.push(
          `Animation track "${clip.name}:${track.name}" targets unknown node "${nodeName}" — rename the pivot or fix the track`,
        );
      }

      if (!['position', 'quaternion', 'scale'].includes(property)) {
        warnings.push(
          `Animation track "${clip.name}:${track.name}" uses unsupported property "${property}"`,
        );
      }
    }
  }

  return warnings;
}

// =============================================================================
// Runtime structural validators (stray planes, floating parts)
// =============================================================================

interface MeshStats {
  object: THREE.Object3D;
  name: string;
  triCount: number;
  isPlaneGeo: boolean;
  center: THREE.Vector3;
  size: THREE.Vector3;
  box: THREE.Box3;
}

interface FloatingPiece extends MeshStats {
  welded?: { mesh: string; index: number; of: number };
}

const spanText = (box: THREE.Box3): string =>
  `[${box.min
    .toArray()
    .map((v) => v.toFixed(3))
    .join(', ')}] to [${box.max
    .toArray()
    .map((v) => v.toFixed(3))
    .join(', ')}]`;

/** One mesh with forty loose components is one entry naming the count and its first one. */
function collapseWeldedFloaters(
  floaters: { name: string; fix: string; welded?: string }[],
  pieces: readonly FloatingPiece[],
): void {
  for (let i = 0; i < floaters.length; i++) {
    const mesh = floaters[i]!.welded;
    if (!mesh) continue;
    const detached = floaters.filter((floater) => floater.welded === mesh).length;
    if (detached < 2) continue;
    const of = pieces.find((piece) => piece.welded?.mesh === mesh)?.welded?.of ?? detached;
    floaters[i]!.name = `${mesh} (${detached} of its ${of} welded components)`;
    for (let j = floaters.length - 1; j > i; j--)
      if (floaters[j]!.welded === mesh) floaters.splice(j, 1);
    floaters[i]!.welded = undefined;
  }
}

function collectMeshStats(root: THREE.Object3D): MeshStats[] {
  root.updateMatrixWorld(true);
  const out: MeshStats[] = [];
  root.traverseVisible((obj) => {
    if (!(obj as { isMesh?: boolean }).isMesh) return;
    const meshObj = obj as THREE.Mesh;
    const geo = meshObj.geometry;
    if (!geo) return;

    const idx = geo.getIndex();
    const tri = idx ? idx.count / 3 : (geo.getAttribute('position')?.count ?? 0) / 3;

    // Measure this drawn mesh alone. setFromObject also includes descendants,
    // including invisible children, and can make a visible body look connected
    // to a hidden part or inflate the orientation advisory's bounds.
    const bounded = meshObj as THREE.Mesh & {
      boundingBox?: THREE.Box3 | null;
      computeBoundingBox?: () => void;
    };
    let localBounds: THREE.Box3 | null;
    if (bounded.boundingBox !== undefined) {
      if (bounded.boundingBox === null) bounded.computeBoundingBox?.();
      localBounds = bounded.boundingBox ?? null;
    } else {
      if (geo.boundingBox === null) geo.computeBoundingBox();
      localBounds = geo.boundingBox;
    }
    if (!localBounds) return;
    const box = localBounds.clone().applyMatrix4(meshObj.matrixWorld);
    if (!Number.isFinite(box.min.x) || !Number.isFinite(box.max.x)) {
      return;
    }
    const center = new THREE.Vector3();
    const size = new THREE.Vector3();
    box.getCenter(center);
    box.getSize(size);

    out.push({
      object: obj,
      name: obj.name || '(unnamed)',
      triCount: Math.floor(tri),
      isPlaneGeo: geo.type === 'PlaneGeometry',
      center,
      size,
      box,
    });
  });
  return out;
}

/**
 * Detects two structural failure modes observed in real overnight runs:
 *
 * 1. **Stray plane at origin** — a 2-triangle `PlaneGeometry` mesh whose
 *    world-space bbox centroid sits within 2cm of world origin. This is
 *    what happens when the model reaches for `planeGeo` as a decal (red
 *    star, stamp, hull number) and forgets to position it on the host
 *    surface. Fix: move the decal into place, or switch to `decalBox`.
 * 2. **Floating part** — a mesh whose world-space bbox has no overlap
 *    (with a 2cm tolerance) with any other mesh in the scene. Fix: move
 *    the mesh so it contacts its intended parent surface.
 *
 * Emits strings compatible with the existing `warnings` channel on
 * `RenderResult`. `_direct-generate.ts` threshold-checks these to trigger
 * a single corrective retry.
 *
 * Floating-part warnings carry an actionable fix: the minimal world-space
 * shift that brings the floater into contact with its nearest sibling (or the
 * `snapTo(part, host)` call that applies it).
 *
 * Pass `opts.category` (vehicle / weapon / boat / aircraft) to additionally
 * run the orientation advisory: kiln assets face +X, so a vehicle whose Z
 * extent dominates its X extent was probably built sideways. Aircraft skip
 * the Z check (wingspan legitimately dominates) and check Y instead.
 */
export interface InspectStructureOptions {
  /** Asset kind for the orientation advisory. Omit to skip it. */
  category?: 'vehicle' | 'weapon' | 'boat' | 'aircraft' | (string & {});
  /** requirements.externalSupport: named parts that rest on a support outside this asset. */
  externalSupport?: readonly ExternalSupportV1[];
}

/** Floating parts named with their own fix; the rest share one line of names. */
const FLOATER_FIXES_SHOWN = 6;
const FLOATER_NAMES_SHOWN = 24;

/** Minimal world-space translation that closes the gap between two boxes
 *  (zero on axes that already overlap). */
function minimalGapVector(a: THREE.Box3, b: THREE.Box3): THREE.Vector3 {
  const v = new THREE.Vector3();
  for (const axis of ['x', 'y', 'z'] as const) {
    if (a.min[axis] > b.max[axis]) v[axis] = b.max[axis] - a.min[axis];
    else if (a.max[axis] < b.min[axis]) v[axis] = b.min[axis] - a.max[axis];
    else v[axis] = 0;
  }
  return v;
}

export function inspectSceneStructure(
  root: THREE.Object3D,
  opts: InspectStructureOptions = {},
): string[] {
  const warnings: string[] = [];
  const meshes = collectMeshStats(root);
  if (meshes.length === 0) return warnings;

  // Orientation advisory (category-aware; runs even for single-mesh scenes).
  const cat = opts.category?.toLowerCase();
  if (cat === 'vehicle' || cat === 'weapon' || cat === 'boat' || cat === 'aircraft') {
    const all = new THREE.Box3();
    for (const m of meshes) all.union(m.box);
    const size = new THREE.Vector3();
    all.getSize(size);
    if (cat === 'aircraft') {
      if (size.y > size.x * 1.2) {
        warnings.push(
          `Orientation: this aircraft is ${size.y.toFixed(2)} tall but only ${size.x.toFixed(2)} long along +X (the nose axis). Kiln aircraft fly nose-first along +X — it may be built vertically or sideways.`,
        );
      }
    } else if (size.z > size.x * 1.3) {
      warnings.push(
        `Orientation: this ${cat} spans ${size.z.toFixed(2)} along Z but only ${size.x.toFixed(2)} along +X. Kiln ${cat}s face +X (forward/muzzle/bow) — it looks built sideways; rebuild the long axis along X.`,
      );
    }
  }

  const STRAY_CENTROID_TOL = 0.02;
  const FLOATING_EXPAND = 0.02;
  const DECAL_EXTENT_MAX = 0.5; // anything smaller than 50cm fits decal profile

  for (const m of meshes) {
    if (!m.isPlaneGeo) continue;
    if (m.triCount > 2) continue;
    if (m.size.length() > DECAL_EXTENT_MAX) continue;
    if (m.center.length() < STRAY_CENTROID_TOL) {
      warnings.push(
        `Stray plane "${m.name}" at world origin (centroid ≈ [0,0,0]). Replace planeGeo with decalBox and position on a host surface, or move this mesh into place.`,
      );
    }
  }

  // A mesh holding several welded components is compared once per component (#304).
  const budget = splitBudget();
  const pieces = meshes.flatMap((mesh): FloatingPiece[] => {
    const boxes = meshComponentBoxes(mesh.object as THREE.Mesh, budget);
    if (!boxes || boxes.length < 2) return [mesh];
    return boxes.map((box, index) => ({
      ...mesh,
      box,
      welded: { mesh: mesh.name, index: index + 1, of: boxes.length },
    }));
  });
  if (pieces.length > 1) {
    const floaters: { name: string; fix: string; welded?: string }[] = [];
    const supported: string[] = [];
    for (let i = 0; i < pieces.length; i++) {
      const a = pieces[i]!;
      const ax = a.box.clone().expandByScalar(FLOATING_EXPAND);
      let overlapsAny = false;
      for (let j = 0; j < pieces.length; j++) {
        if (i === j) continue;
        const b = pieces[j]!;
        if (ax.intersectsBox(b.box)) {
          overlapsAny = true;
          break;
        }
      }
      if (overlapsAny) continue;
      // A declared external support whose plane this part's bottom meets is information.
      const support = restingSupport(a.object, a.box.min.y, opts.externalSupport);
      if (support) {
        supported.push(`${a.name} at Y=${support.planeY.toFixed(3)}`);
        continue;
      }
      const declared = declaredSupports(a.object, opts.externalSupport)[0];

      // Actionable fix: the minimal shift to the NEAREST sibling, plus the
      // snapTo call that applies it.
      let nearest: FloatingPiece | undefined;
      let nearestGap: THREE.Vector3 | undefined;
      for (let j = 0; j < pieces.length; j++) {
        if (i === j) continue;
        const gap = minimalGapVector(a.box, pieces[j]!.box);
        if (!nearestGap || gap.length() < nearestGap.length()) {
          nearest = pieces[j]!;
          nearestGap = gap;
        }
      }
      const fix = a.welded
        ? ` Fix: one mesh moves and hides as one, so close the gap in the merged geometry, or author the component as its own part. It spans ${spanText(a.box)}.`
        : nearest && nearestGap
          ? ` Fix: shift "${a.name}" by [${nearestGap.x.toFixed(3)}, ${nearestGap.y.toFixed(3)}, ${nearestGap.z.toFixed(3)}] toward "${nearest.name}", or call snapTo(part, hostPart) to do it automatically.`
          : '';
      const mismatch = declared
        ? ` It is named in a declared external support at Y=${declared.planeY.toFixed(3)}, but its bottom is at Y=${a.box.min.y.toFixed(3)}.`
        : '';
      const name = a.welded
        ? `${a.welded.mesh} (welded component ${a.welded.index} of ${a.welded.of})`
        : a.name;
      floaters.push({
        name,
        fix: fix + mismatch,
        ...(a.welded ? { welded: a.welded.mesh } : {}),
      });
    }
    collapseWeldedFloaters(floaters, pieces);
    if (floaters.length > 0) {
      // The per-part fix text is 170 characters; a scattered asset repeated it
      // for every part. The first few floaters keep their fix, the rest are
      // named, and the names are bounded too.
      const entries = floaters
        .slice(0, FLOATER_FIXES_SHOWN)
        .map(({ name, fix }) => `${name}${fix ? ` —${fix}` : ''}`);
      const rest = floaters.slice(FLOATER_FIXES_SHOWN);
      if (rest.length > 0) {
        const names = rest.slice(0, FLOATER_NAMES_SHOWN).map((floater) => floater.name);
        if (rest.length > names.length) names.push(`+${rest.length - names.length} more`);
        entries.push(
          `+${rest.length} more floating: ${names.join(', ')} — the same fix applies: shift each onto its nearest sibling, or call snapTo(part, hostPart).`,
        );
      }
      warnings.push(
        `Floating parts (no mesh overlap with any sibling, 2cm tol): ${entries.join(' | ')} — Coverage: drawn meshes only, at 2cm. Welded components inside one mesh are compared the same way, box to box. A smaller gap reads as contact, so a silent pass is not a fit audit; measure contacts in the destination.${budget.unsplit.length ? ` Over the split budget, so measured as one box: ${budget.unsplit.slice(0, FLOATER_NAMES_SHOWN).join(', ')}.` : ''}`,
      );
    }
    if (supported.length > 0) {
      const shown = supported.slice(0, FLOATER_NAMES_SHOWN);
      if (supported.length > shown.length) shown.push(`+${supported.length - shown.length} more`);
      warnings.push(
        `Declared external support (requirements.externalSupport): ${shown.join(', ')} rest on a support composed outside this asset; information only, no action needed.`,
      );
    }
  }

  return warnings;
}

/**
 * OPT-IN geometry settle: translate each floating mesh into contact with its
 * nearest sibling, but only when the gap is small (≤ `maxGap`). Deliberately
 * NOT applied inside kiln_render or renderGLB — silently mutating geometry
 * would desync the code from the artifact and poison refine loops. The batch
 * harness uses it after a soft-retry still warns, and records the settled part
 * names in provenance so the mutation is visible.
 *
 * Returns the names of the parts that were moved.
 */
export function settleContacts(
  root: THREE.Object3D,
  opts: { maxGap?: number; overlap?: number } = {},
): string[] {
  const maxGap = opts.maxGap ?? 0.05;
  const overlap = opts.overlap ?? 0.01;
  const settled: string[] = [];

  // One move per pass, then re-collect: moving a part changes every other
  // part's floating status (with two meshes BOTH read as floaters — moving
  // either resolves both). Among the settleable floaters, move the smallest
  // (it's the attachment, not the hull).
  for (let pass = 0; pass < 8; pass++) {
    const meshes = collectMeshStats(root);
    if (meshes.length < 2) return settled;

    let pick: { stats: MeshStats; gap: THREE.Vector3; volume: number } | undefined;
    for (let i = 0; i < meshes.length; i++) {
      const a = meshes[i]!;
      const ax = a.box.clone().expandByScalar(0.02);
      if (meshes.some((b, j) => j !== i && ax.intersectsBox(b.box))) continue;

      let nearestGap: THREE.Vector3 | undefined;
      for (let j = 0; j < meshes.length; j++) {
        if (i === j) continue;
        const gap = minimalGapVector(a.box, meshes[j]!.box);
        if (!nearestGap || gap.length() < nearestGap.length()) nearestGap = gap;
      }
      if (!nearestGap || nearestGap.length() === 0 || nearestGap.length() > maxGap) continue;

      const volume = a.size.x * a.size.y * a.size.z;
      if (!pick || volume < pick.volume) pick = { stats: a, gap: nearestGap, volume };
    }
    if (!pick) break;

    // Close the gap plus a small overlap along the dominant gap axis.
    const delta = pick.gap.clone();
    const dominant = (['x', 'y', 'z'] as const).reduce(
      (d, axis) => (Math.abs(delta[axis]) > Math.abs(delta[d]) ? axis : d),
      'x' as 'x' | 'y' | 'z',
    );
    delta[dominant] += Math.sign(delta[dominant]) * overlap;

    // Find the named object and move it, converting the world delta into the
    // parent's local space (handles rotated/scaled ancestors).
    let target: THREE.Object3D | undefined;
    root.traverse((obj) => {
      if (!target && obj.name === pick!.stats.name && (obj as { isMesh?: boolean }).isMesh)
        target = obj;
    });
    if (!target) break;
    const parent = target.parent ?? root;
    const p0 = new THREE.Vector3();
    target.getWorldPosition(p0);
    const p1 = p0.clone().add(delta);
    const l0 = parent.worldToLocal(p0.clone());
    const l1 = parent.worldToLocal(p1.clone());
    target.position.add(l1.sub(l0));
    target.updateMatrixWorld(true);
    settled.push(pick.stats.name);
  }
  return settled;
}