Skip to content

3D engine that AI agents drive

41.5 KB
Raw Blame
import { editMesh, meshData } from './mesh-edit.js';
import { invalidField } from './field-error.js';
import { editField, editBoolean } from './mesh-edit-field.js';
import { countSelected, selectFaces } from './mesh-select.js';
import {
  extrudeFaceRegion, extrudeIndividual, insetRegion, insetIndividual, deleteFaces, flipFaces, translateFaces, transformFaces, mergeByDistance, tagFaces,
  FALLOFF_CURVES,
} from './mesh-ops.js';
import { meshBoolean, BOOLEAN_OPERATIONS } from './mesh-boolean.js';
import { createMeshData } from './mesh-data.js';
import { mirrorMesh, arrayMesh, solidifyMesh } from './mesh-stack.js';
import { bevelEdges, MAX_BEVEL_SEGMENTS } from './mesh-bevel.js';
import { loopCut, MAX_LOOP_CUTS } from './mesh-loopcut.js';
import { CUT_OPERATIONS, normalizeCutEdit, runCutEdit, checkCutBudget } from './mesh-cut-edits.js';
import { RESHAPE_OPERATIONS, normalizeReshapeEdit, runReshapeEdit, checkReshapeBudget } from './mesh-reshape-edits.js';
import { unwrapUv } from './mesh-uv.js';
import { projectUv, packUvIslands, UV_PROJECTION_MODES } from './mesh-uv-project.js';
import { runKernel, KernelDeferred } from './kernel-offload.js';
import { validateField } from './mesh-fields.js';
import { setPosition, displaceMesh, DISPLACE_DIRECTIONS } from './mesh-field-edits.js';
import { normalizeVertexColorEdit, normalizeVertexGroupEdit, setVertexColor, setVertexGroup } from './mesh-attribute-edits.js';
import { subdivideMesh, subdivisionSize, MAX_SUBDIVISION_LEVELS, MAX_CREASE_SHARPNESS } from './mesh-subdivide.js';
import { decimateMesh } from './mesh-decimate.js';
import { isModifierOperation, normalizeModifierEdit, runModifierEdit } from './mesh-modifiers.js';
import { sculptMesh, checkSculptBudget } from './mesh-sculpt.js';
import { shrinkwrapMesh } from './mesh-shrinkwrap.js';
import { triangulatedSurface } from './mesh-surface-distance.js';
import { createTriangleSurfaceIndex } from './mesh-query.js';
import './mesh-field-surfaces.js';
import './field-rotation.js';
import './field-mesh-inputs.js';
import './mesh-hull-modifiers.js';
import './mesh-ocean-modifier.js';
import './mesh-build-modifier.js';
import { remeshMesh, remeshGridSize, MAX_REMESH_RESOLUTION } from './mesh-remesh.js';
import {
  MESH_EDIT_OPERATIONS, MAX_MESH_EDITS, STACK_OPERATIONS, MAX_STACK_NODES, SCULPT_STROKE_TYPES, MAX_SCULPT_STROKES, SHRINKWRAP_MODES,
} from './mesh-operations.js';
export { MESH_EDIT_OPERATIONS, MAX_MESH_EDITS, STACK_OPERATIONS, MAX_STACK_NODES };

// Replayable edit log for agent recipes. Each edit is plain JSON; names follow Blender's bmesh.ops where they match.

const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,47}$/;
const MAX_OFFSET = 1e6;


// A failure inside an edit keeps its field path when it has one, so the agent sees edits[2].maxDistance, and otherwise
// gets the edit position and name in front of the message.
function editFailure(error, index, label) {
  if (typeof error?.fieldPath === 'string' && error.message.startsWith(error.fieldPath)) {
    error.message = `edits[${index}].${error.message}`;
    error.fieldPath = `edits[${index}].${error.fieldPath}`;
    return error;
  }
  return new error.constructor(`Mesh edit ${index} (${label}): ${error.message}`);
}

function finiteNumber(value, index, label, { minimum = -MAX_OFFSET, maximum = MAX_OFFSET, exclusiveMinimum = false } = {}) {
  if (typeof value !== 'number' || !Number.isFinite(value) || value < minimum || value > maximum || (exclusiveMinimum && value === minimum)) {
    throw editField(index, label, value, `a number ${exclusiveMinimum ? 'above' : 'from'} ${minimum}${maximum < MAX_OFFSET ? ` to ${maximum}` : ''}, such as ${exclusiveMinimum ? minimum + 1 : Math.min(Math.max(1, minimum), maximum)}`);
  }
  return value;
}

function vector(value, index, label) {
  if (!Array.isArray(value) || value.length !== 3) throw editField(index, label, value, 'an array of three numbers, such as [0, 1, 0]');
  return value.map(component => finiteNumber(component, index, label));
}

function checkedField(expression, index, label, kind) {
  try {
    validateField(expression, { kind });
  } catch (error) {
    throw editField(index, label, expression, `a ${kind} field expression such as ${kind === 'vector' ? '[0, 1, 0]' : '0.5'} (${error.message})`);
  }
  return expression;
}

/** translation, rotation (XYZW quaternion) and scale that place a primitive in the mesh's local space. */
function normalizePlacement(edit, normalized, index) {
  normalized.translation = edit.translation === undefined ? [0, 0, 0] : vector(edit.translation, index, 'translation');
  normalized.scale = edit.scale === undefined ? [1, 1, 1] : vector(edit.scale, index, 'scale');
  if (normalized.scale.some(value => value <= 0)) throw editField(index, 'scale', normalized.scale, 'three numbers above 0, such as [1, 1, 1]');
  if (edit.rotation === undefined) {
    normalized.rotation = [0, 0, 0, 1];
    return;
  }
  if (!Array.isArray(edit.rotation) || edit.rotation.length !== 4) throw editField(index, 'rotation', edit.rotation, 'an XYZW quaternion of four numbers, such as [0, 0, 0, 1]');
  const rotation = edit.rotation.map(component => finiteNumber(component, index, 'rotation'));
  const length = Math.hypot(...rotation);
  if (length === 0) throw editField(index, 'rotation', rotation, 'a nonzero XYZW quaternion, such as [0, 0, 0, 1]');
  normalized.rotation = rotation.map(component => component / length);
}

function normalizeStroke(stroke, index, strokeIndex) {
  const label = `strokes[${strokeIndex}]`;
  if (!stroke || typeof stroke !== 'object' || Array.isArray(stroke)) throw editField(index, label, stroke, `an object such as { "type": "${SCULPT_STROKE_TYPES[0]}", "center": [0, 0, 0], "radius": 0.5, "strength": 0.2 }`);
  for (const key of Object.keys(stroke)) {
    if (!['type', 'center', 'radius', 'strength', 'direction'].includes(key)) throw editField(index, `${label}.${key}`, stroke[key], `one of the stroke fields type, center, radius, strength, direction; remove "${key}"`);
  }
  if (!SCULPT_STROKE_TYPES.includes(stroke.type)) throw editField(index, `${label}.type`, stroke.type, `one of ${SCULPT_STROKE_TYPES.join(', ')}`);
  const normalized = {
    type: stroke.type,
    center: vector(stroke.center, index, `${label}.center`),
    radius: finiteNumber(stroke.radius, index, `${label}.radius`, { minimum: 0, exclusiveMinimum: true }),
    strength: finiteNumber(stroke.strength, index, `${label}.strength`),
  };
  if (stroke.type === 'smooth' && (normalized.strength < 0 || normalized.strength > 1)) throw editField(index, `${label}.strength`, normalized.strength, 'a number from 0 to 1 for a smooth stroke, such as 0.5');
  if (stroke.type === 'displace') {
    normalized.direction = vector(stroke.direction, index, `${label}.direction`);
    if (normalized.direction.every(component => component === 0)) throw editField(index, `${label}.direction`, normalized.direction, 'a nonzero direction, such as [0, 0, 1]');
  } else if (stroke.direction !== undefined) {
    throw editField(index, `${label}.direction`, stroke.direction, 'left out, because only a displace stroke takes direction');
  }
  return normalized;
}

function normalizeFalloff(falloff, index) {
  if (!falloff || typeof falloff !== 'object') throw editField(index, 'falloff', falloff, 'an object such as { "radius": 1, "curve": "smooth", "connected": false }');
  for (const key of Object.keys(falloff)) {
    if (!['radius', 'curve', 'connected'].includes(key)) throw editField(index, `falloff.${key}`, falloff[key], `one of the falloff fields radius, curve, connected; remove "${key}"`);
  }
  const curve = falloff.curve ?? 'smooth';
  if (!Object.hasOwn(FALLOFF_CURVES, curve)) throw editField(index, 'falloff.curve', curve, `one of ${Object.keys(FALLOFF_CURVES).join(', ')}`);
  if (falloff.connected !== undefined && typeof falloff.connected !== 'boolean') throw editField(index, 'falloff.connected', falloff.connected, 'true or false');
  return {
    radius: finiteNumber(falloff.radius, index, 'falloff.radius', { minimum: 0, exclusiveMinimum: true }),
    curve, connected: falloff.connected ?? false,
  };
}

const MAX_TRANSFORM_SCALE = 1000;

function normalizeTransformRotation(rotation, index) {
  if (!rotation || typeof rotation !== 'object' || Array.isArray(rotation)) throw editField(index, 'rotation', rotation, 'an object such as { "axis": [0, 1, 0], "angle": 1.5708 } (angle in radians)');
  for (const key of Object.keys(rotation)) {
    if (!['axis', 'angle'].includes(key)) throw editField(index, `rotation.${key}`, rotation[key], `one of the rotation fields axis, angle; remove "${key}"`);
  }
  const axis = vector(rotation.axis, index, 'rotation.axis');
  if (axis.every(component => component === 0)) throw editField(index, 'rotation.axis', axis, 'a direction that is not all zeros, such as [0, 1, 0]');
  const angle = finiteNumber(rotation.angle, index, 'rotation.angle', { minimum: -2 * Math.PI, maximum: 2 * Math.PI });
  return { axis, angle };
}

function normalizeTransformScale(scale, index) {
  const bounds = { minimum: 0, maximum: MAX_TRANSFORM_SCALE, exclusiveMinimum: true };
  if (!Array.isArray(scale)) return finiteNumber(scale, index, 'scale', bounds);
  if (scale.length !== 3) throw editField(index, 'scale', scale, 'one number above 0, or an array of three, such as 0.5 or [1, 2, 1]');
  return scale.map(component => finiteNumber(component, index, 'scale', bounds));
}

// rotation.angle is radians; a value in degrees is the usual slip, so the bound error says so.
function normalizeTransformSelection(edit, normalized, index) {
  if (edit.rotation === undefined && edit.scale === undefined) throw editField(index, 'rotation', undefined, 'a rotation such as { "axis": [0, 1, 0], "angle": 0.5 } (radians; 90 degrees is 1.5708), a scale such as 0.5, or both');
  if (edit.pivot !== undefined) normalized.pivot = vector(edit.pivot, index, 'pivot');
  if (edit.rotation !== undefined) {
    try {
      normalized.rotation = normalizeTransformRotation(edit.rotation, index);
    } catch (error) {
      if (error.fieldPath?.endsWith('rotation.angle')) error.message += ' The angle is in radians (90 degrees is 1.5708), not degrees.';
      throw error;
    }
  }
  if (edit.scale !== undefined) normalized.scale = normalizeTransformScale(edit.scale, index);
  if (edit.falloff !== undefined) normalized.falloff = normalizeFalloff(edit.falloff, index);
}

/** Validate an edit list without running it. Returns normalized copies with default names filled in. */
export function normalizeMeshEdits(edits) {
  if (!Array.isArray(edits)) throw invalidField('edits', edits, 'an array of edits, such as [{ "op": "subdivide", "levels": 1 }]', TypeError);
  if (edits.length > MAX_MESH_EDITS) throw new RangeError(`A mesh holds at most ${MAX_MESH_EDITS} edits. Apply fewer or start from a new base.`);
  return edits.map((edit, index) => {
    if (!edit || typeof edit !== 'object' || Array.isArray(edit)) throw invalidField(`edits[${index}]`, edit, 'an object such as { "op": "subdivide", "levels": 1 }', TypeError);
    const definition = Object.hasOwn(MESH_EDIT_OPERATIONS, edit.op) ? MESH_EDIT_OPERATIONS[edit.op] : undefined;
    if (!definition) throw editField(index, 'op', edit.op, `one of ${Object.keys(MESH_EDIT_OPERATIONS).join(', ')}`);
    for (const key of Object.keys(edit)) {
      if (key !== 'op' && !definition.fields.includes(key)) throw editField(index, key, edit[key], `one of the fields ${edit.op} takes: ${definition.fields.join(', ')}; remove "${key}"`);
    }
    const normalized = { op: edit.op };
    if (definition.fields.includes('select')) {
      if (edit.select === undefined && ['delete', 'tag', 'dissolve_faces'].includes(edit.op)) throw editField(index, 'select', edit.select, 'a face rule such as { "all": true } or { "tag": "top" }');
      normalized.select = edit.select ?? { all: true };
    }
    if (definition.fields.includes('name')) {
      const name = edit.name ?? (['tag', 'vertex_group'].includes(edit.op) ? undefined : `${edit.op.split('_')[0]}-${index + 1}`);
      if (typeof name !== 'string' || !NAME_PATTERN.test(name)) throw editField(index, 'name', name, '1 to 48 letters, digits, dots, dashes or underscores, such as "lid.cap"');
      normalized.name = name;
    }
    switch (edit.op) {
      case 'extrude_face_region':
      case 'extrude_individual':
        normalized.offset = finiteNumber(edit.offset, index, 'offset');
        if (edit.direction !== undefined) normalized.direction = vector(edit.direction, index, 'direction');
        if (edit.alongNormals !== undefined) {
          if (typeof edit.alongNormals !== 'boolean') throw editField(index, 'alongNormals', edit.alongNormals, 'true or false');
          if (edit.alongNormals && edit.direction !== undefined) throw editField(index, 'direction', edit.direction, 'left out when alongNormals is true');
          normalized.alongNormals = edit.alongNormals;
        }
        break;
      case 'inset_region':
      case 'inset_individual':
        normalized.thickness = finiteNumber(edit.thickness, index, 'thickness', { minimum: 0, exclusiveMinimum: true });
        normalized.depth = edit.depth === undefined ? 0 : finiteNumber(edit.depth, index, 'depth');
        break;
      case 'translate':
        normalized.offset = vector(edit.offset, index, 'offset');
        if (edit.falloff !== undefined) normalized.falloff = normalizeFalloff(edit.falloff, index);
        break;
      case 'transform_selection':
        normalizeTransformSelection(edit, normalized, index);
        break;
      case 'boolean': {
        if (!BOOLEAN_OPERATIONS.includes(edit.operation)) throw editField(index, 'operation', edit.operation, `one of ${BOOLEAN_OPERATIONS.join(', ')}`);
        normalized.operation = edit.operation;
        const isRecord = edit.cutter && typeof edit.cutter === 'object' && !Array.isArray(edit.cutter);
        const namesGeometry = isRecord && Object.hasOwn(edit.cutter, 'geometry');
        if (!isRecord || (!namesGeometry && typeof edit.cutter.type !== 'string')) {
          throw editField(index, 'cutter', edit.cutter, 'a primitive record such as { "type": "cylinder", "segments": 32 } or a recipe geometry such as { "geometry": "tool" }');
        }
        normalized.cutter = edit.cutter;
        normalizePlacement(edit, normalized, index);
        break;
      }
      case 'sculpt':
        if (!Array.isArray(edit.strokes) || edit.strokes.length < 1 || edit.strokes.length > MAX_SCULPT_STROKES) {
          throw editField(index, 'strokes', edit.strokes, `an array of 1 to ${MAX_SCULPT_STROKES} brush strokes, such as [{ "type": "${SCULPT_STROKE_TYPES[0]}", "center": [0, 0, 0], "radius": 0.5, "strength": 0.2 }]`);
        }
        normalized.strokes = edit.strokes.map((stroke, strokeIndex) => normalizeStroke(stroke, index, strokeIndex));
        break;
      case 'shrinkwrap':
        if (!edit.target || typeof edit.target !== 'object' || Array.isArray(edit.target) || typeof edit.target.type !== 'string') {
          throw editField(index, 'target', edit.target, 'a primitive record such as { "type": "sphere", "radius": 0.5 }');
        }
        normalized.target = edit.target;
        normalizePlacement(edit, normalized, index);
        if (!SHRINKWRAP_MODES.includes(edit.mode ?? 'nearest')) throw editField(index, 'mode', edit.mode, `one of ${SHRINKWRAP_MODES.join(', ')}`);
        normalized.mode = edit.mode ?? 'nearest';
        if (normalized.mode === 'project') {
          normalized.direction = vector(edit.direction, index, 'direction');
          if (normalized.direction.every(component => component === 0)) throw editField(index, 'direction', normalized.direction, 'a nonzero direction, such as [0, -1, 0]');
        } else if (edit.direction !== undefined) {
          throw editField(index, 'direction', edit.direction, 'left out unless mode is "project"');
        }
        normalized.offset = edit.offset === undefined ? 0 : finiteNumber(edit.offset, index, 'offset', { minimum: 0 });
        if (edit.maxDistance !== undefined) normalized.maxDistance = finiteNumber(edit.maxDistance, index, 'maxDistance', { minimum: 0 });
        if (!['error', 'keep'].includes(edit.onMiss ?? 'error')) throw editField(index, 'onMiss', edit.onMiss, '"error" or "keep"');
        normalized.onMiss = edit.onMiss ?? 'error';
        break;
      case 'mirror':
        if (!['x', 'y', 'z'].includes(edit.axis ?? 'x')) throw editField(index, 'axis', edit.axis, '"x", "y" or "z"');
        normalized.axis = edit.axis ?? 'x';
        normalized.merge = edit.merge === undefined ? 0.001 : finiteNumber(edit.merge, index, 'merge', { minimum: 0, maximum: 1e3 });
        break;
      case 'array':
        if (!Number.isInteger(edit.count ?? 2) || (edit.count ?? 2) < 1 || (edit.count ?? 2) > 256) throw editField(index, 'count', edit.count, 'a whole number from 1 to 256, such as 4');
        normalized.count = edit.count ?? 2;
        normalized.offset = edit.offset === undefined ? [0, 0, 0] : vector(edit.offset, index, 'offset');
        normalized.relativeOffset = edit.relativeOffset === undefined ? (edit.offset === undefined ? [1, 0, 0] : [0, 0, 0]) : vector(edit.relativeOffset, index, 'relativeOffset');
        normalized.merge = edit.merge === undefined ? 0 : finiteNumber(edit.merge, index, 'merge', { minimum: 0, maximum: 1e3 });
        break;
      case 'solidify':
        normalized.thickness = finiteNumber(edit.thickness, index, 'thickness', { minimum: 0, exclusiveMinimum: true });
        normalized.offset = edit.offset === undefined ? -1 : finiteNumber(edit.offset, index, 'offset', { minimum: -1, maximum: 1 });
        if (edit.evenThickness !== undefined && typeof edit.evenThickness !== 'boolean') throw editField(index, 'evenThickness', edit.evenThickness, 'true or false');
        normalized.evenThickness = edit.evenThickness ?? true;
        break;
      case 'bevel':
        if (edit.edges !== undefined && (!edit.edges || typeof edit.edges !== 'object' || Array.isArray(edit.edges))) {
          throw editField(index, 'edges', edit.edges, 'an edge rule such as { "all": true }, { "angle": 30 }, { "between": [faceRule, faceRule] } or { "boundaryOf": faceRule }');
        }
        normalized.edges = edit.edges ?? { angle: 30 };
        normalized.width = finiteNumber(edit.width, index, 'width', { minimum: 0, exclusiveMinimum: true });
        if (!Number.isInteger(edit.segments ?? 1) || (edit.segments ?? 1) < 1 || (edit.segments ?? 1) > MAX_BEVEL_SEGMENTS) throw editField(index, 'segments', edit.segments, `a whole number from 1 to ${MAX_BEVEL_SEGMENTS}, such as 3`);
        normalized.segments = edit.segments ?? 1;
        normalized.profile = edit.profile === undefined ? 0.5 : finiteNumber(edit.profile, index, 'profile', { minimum: 0, maximum: 1 });
        if (edit.clampOverlap !== undefined && typeof edit.clampOverlap !== 'boolean') throw editField(index, 'clampOverlap', edit.clampOverlap, 'true or false');
        normalized.clampOverlap = edit.clampOverlap ?? true;
        break;
      case 'loop_cut':
        if (!edit.edges || typeof edit.edges !== 'object' || Array.isArray(edit.edges)) {
          throw editField(index, 'edges', edit.edges, 'a rule that picks the ring, such as { "along": [0, 1, 0] } for the vertical edges');
        }
        normalized.edges = edit.edges;
        if (!Number.isInteger(edit.cuts ?? 1) || (edit.cuts ?? 1) < 1 || (edit.cuts ?? 1) > MAX_LOOP_CUTS) throw editField(index, 'cuts', edit.cuts, `a whole number from 1 to ${MAX_LOOP_CUTS}, such as 1`);
        normalized.cuts = edit.cuts ?? 1;
        if (edit.factor !== undefined && normalized.cuts !== 1) throw editField(index, 'factor', edit.factor, 'left out when cuts is above 1, because factor applies only to a single cut');
        normalized.factor = edit.factor === undefined ? 0.5 : finiteNumber(edit.factor, index, 'factor', { minimum: 0, maximum: 1 });
        if (normalized.factor === 0 || normalized.factor === 1) throw editField(index, 'factor', normalized.factor, 'a number above 0 and below 1, such as 0.5');
        break;
      case 'uv_unwrap':
        if (edit.seams !== undefined && (!edit.seams || typeof edit.seams !== 'object' || Array.isArray(edit.seams))) {
          throw editField(index, 'seams', edit.seams, 'an edge rule such as { "angle": 60 } or { "boundaryOf": { "tag": "lid.cap" } }');
        }
        normalized.seams = edit.seams ?? { angle: 60 };
        normalized.margin = edit.margin === undefined ? 0.01 : finiteNumber(edit.margin, index, 'margin', { minimum: 0, maximum: 0.2 });
        normalized.maxDistortion = edit.maxDistortion === undefined ? 0.25 : finiteNumber(edit.maxDistortion, index, 'maxDistortion', { minimum: 0, maximum: 100 });
        break;
      case 'uv_project':
        if (!UV_PROJECTION_MODES.includes(edit.mode)) throw editField(index, 'mode', edit.mode, `one of ${UV_PROJECTION_MODES.join(', ')}`);
        normalized.mode = edit.mode;
        if (!['x', 'y', 'z'].includes(edit.axis ?? 'y')) throw editField(index, 'axis', edit.axis, '"x", "y" or "z", the cylinder or sphere axis');
        normalized.axis = edit.axis ?? 'y';
        normalized.pack = edit.pack ?? true;
        normalized.margin = edit.margin === undefined ? 0.01 : finiteNumber(edit.margin, index, 'margin', { minimum: 0, maximum: 0.2 });
        normalized.rotate = edit.rotate ?? true;
        editBoolean(normalized.pack, index, 'pack');
        editBoolean(normalized.rotate, index, 'rotate');
        break;
      case 'uv_pack':
        normalized.margin = edit.margin === undefined ? 0.01 : finiteNumber(edit.margin, index, 'margin', { minimum: 0, maximum: 0.2 });
        normalized.rotate = edit.rotate ?? true;
        editBoolean(normalized.rotate, index, 'rotate');
        break;
      case 'subdivide':
        if (!Number.isInteger(edit.levels ?? 1) || (edit.levels ?? 1) < 1 || (edit.levels ?? 1) > MAX_SUBDIVISION_LEVELS) {
          throw editField(index, 'levels', edit.levels, `a whole number from 1 to ${MAX_SUBDIVISION_LEVELS}, such as 1`);
        }
        normalized.levels = edit.levels ?? 1;
        if (edit.crease !== undefined) {
          if (!edit.crease || typeof edit.crease !== 'object' || Array.isArray(edit.crease)) {
            throw editField(index, 'crease', edit.crease, 'an edge rule such as { "angle": 60 } or { "between": [faceRule, faceRule] }');
          }
          normalized.crease = edit.crease;
          normalized.sharpness = edit.sharpness === undefined
            ? MAX_CREASE_SHARPNESS
            : finiteNumber(edit.sharpness, index, 'sharpness', { minimum: 0, maximum: MAX_CREASE_SHARPNESS, exclusiveMinimum: true });
        } else if (edit.sharpness !== undefined) {
          throw editField(index, 'sharpness', edit.sharpness, 'left out unless a crease rule is given, such as "crease": { "angle": 60 }');
        }
        break;
      case 'set_position':
        if (edit.position === undefined && edit.offset === undefined) throw editField(index, 'position', undefined, 'a vector field expression such as [0, 1, 0], given as position or as offset');
        if (edit.position !== undefined) normalized.position = checkedField(edit.position, index, 'position', 'vector');
        if (edit.offset !== undefined) normalized.offset = checkedField(edit.offset, index, 'offset', 'vector');
        break;
      case 'displace':
        normalized.field = checkedField(edit.field, index, 'field', 'scalar');
        normalized.strength = edit.strength === undefined ? 1 : finiteNumber(edit.strength, index, 'strength');
        normalized.midlevel = edit.midlevel === undefined ? 0.5 : finiteNumber(edit.midlevel, index, 'midlevel');
        if (edit.direction !== undefined && !DISPLACE_DIRECTIONS.includes(edit.direction)) throw editField(index, 'direction', edit.direction, `one of ${DISPLACE_DIRECTIONS.join(', ')}`);
        normalized.direction = edit.direction ?? 'normal';
        if (edit.group !== undefined) {
          if (typeof edit.group !== 'string' || !NAME_PATTERN.test(edit.group)) throw editField(index, 'group', edit.group, '1 to 48 letters, digits, dots, dashes or underscores naming a vertex group, such as "mask"');
          normalized.group = edit.group;
        }
        break;
      case 'vertex_group':
        normalizeVertexGroupEdit(edit, normalized, index, { finiteNumber, checkedField });
        break;
      case 'vertex_color':
        normalizeVertexColorEdit(edit, normalized, index, { finiteNumber, checkedField });
        break;
      case 'decimate':
        normalized.ratio = finiteNumber(edit.ratio, index, 'ratio', { minimum: 0, maximum: 1, exclusiveMinimum: true });
        break;
      case 'remesh':
        if ((edit.voxelSize === undefined) === (edit.resolution === undefined)) throw editField(index, 'voxelSize', edit.voxelSize, 'exactly one of voxelSize and resolution, such as "voxelSize": 0.1');
        if (edit.voxelSize !== undefined) normalized.voxelSize = finiteNumber(edit.voxelSize, index, 'voxelSize', { minimum: 0, exclusiveMinimum: true });
        if (edit.resolution !== undefined) {
          if (!Number.isInteger(edit.resolution) || edit.resolution < 4 || edit.resolution > MAX_REMESH_RESOLUTION) {
            throw editField(index, 'resolution', edit.resolution, `a whole number from 4 to ${MAX_REMESH_RESOLUTION}, such as 32`);
          }
          normalized.resolution = edit.resolution;
        }
        break;
      case 'merge_by_distance':
        normalized.distance =finiteNumber(edit.distance ?? 1e-4, index, 'distance', { minimum: 0, maximum: 1e3 });
        break;
    }
    if (CUT_OPERATIONS.includes(edit.op)) normalizeCutEdit(edit, normalized, index, { finiteNumber, vector });
    if (RESHAPE_OPERATIONS.includes(edit.op)) normalizeReshapeEdit(edit, normalized, index, { finiteNumber, vector });
    if (isModifierOperation(edit.op)) normalizeModifierEdit(edit, normalized, index, { finiteNumber, checkedField });
    return normalized;
  });
}

// An array multiplies a mesh in one step, so its size must be known before it allocates.
function checkSubdivideBudget(mesh, edit, limits, index) {
  const size = subdivisionSize(mesh, edit.levels);
  if (size.vertices > limits.maxVertices || size.faces > limits.maxFaces) {
    throw editField(index, 'levels', edit.levels, `a number of levels that keeps the mesh within ${limits.maxVertices} vertices and ${limits.maxFaces} faces (this edit would make ${size.vertices} vertices and ${size.faces} faces), such as 1, or use a simpler mesh`, RangeError);
  }
}

function checkArrayBudget(mesh, edit, limits, index) {
  checkCutBudget(mesh, edit, limits, index);
  checkReshapeBudget(mesh, edit, limits, index);
  if (edit.op === 'sculpt') {
    try {
      checkSculptBudget(mesh, edit.strokes.length);
    } catch (error) {
      throw editFailure(error, index, `sculpt`);
    }
    return;
  }
  if (edit.op === 'subdivide') {
    checkSubdivideBudget(mesh, edit, limits, index);
    return;
  }
  if (edit.op === 'remesh') {
    try {
      remeshGridSize(mesh, edit);
    } catch (error) {
      throw editFailure(error, index, `remesh`);
    }
    return;
  }
  if (edit.op !== 'array') return;
  const vertices = mesh.vertexCount * edit.count;
  const faces = mesh.faceCount * edit.count;
  if (vertices > limits.maxVertices || faces > limits.maxFaces) {
    throw editField(index, 'count', edit.count, `a count that keeps the mesh within ${limits.maxVertices} vertices and ${limits.maxFaces} faces (this edit would make ${vertices} vertices and ${faces} faces), such as 2, or use a simpler mesh`, RangeError);
  }
}

function checkBudget(mesh, limits, index, op) {
  if (mesh.vertexCount > limits.maxVertices || mesh.faceCount > limits.maxFaces) {
    throw new RangeError(`Mesh edit ${index} (${op}) grows the mesh to ${mesh.vertexCount} vertices and ${mesh.faceCount} faces, over the limit of ${limits.maxVertices} vertices or ${limits.maxFaces} faces.`);
  }
}

/** Copy of a mesh with positions scaled, rotated by a unit XYZW quaternion, then translated. */
export function transformMesh(mesh, { translation, rotation, scale }) {
  const [x, y, z, w] = rotation;
  const positions = new Float32Array(mesh.positions.length);
  for (let offset = 0; offset < positions.length; offset += 3) {
    const pointX = mesh.positions[offset] * scale[0];
    const pointY = mesh.positions[offset + 1] * scale[1];
    const pointZ = mesh.positions[offset + 2] * scale[2];
    // v' = v + 2w(q x v) + 2q x (q x v)
    const crossX = y * pointZ - z * pointY;
    const crossY = z * pointX - x * pointZ;
    const crossZ = x * pointY - y * pointX;
    positions[offset] = pointX + 2 * (w * crossX + y * crossZ - z * crossY) + translation[0];
    positions[offset + 1] = pointY + 2 * (w * crossY + z * crossX - x * crossZ) + translation[1];
    positions[offset + 2] = pointZ + 2 * (w * crossZ + x * crossY - y * crossX) + translation[2];
  }
  return createMeshData({
    positions, faceOffsets: mesh.faceOffsets, cornerVertices: mesh.cornerVertices,
    edgeVertices: mesh.edgeVertices, cornerEdges: mesh.cornerEdges, attributes: mesh.attributes,
  });
}

function runShrinkwrap(current, edit, resolveCutter) {
  if (!resolveCutter) throw new TypeError('shrinkwrap needs a target resolver; recipe meshes provide one.');
  return shrinkwrapMesh(current, transformMesh(resolveCutter(edit.target), edit), edit);
}

/** Run one normalized edit on MeshData and describe what it did. */
// Field inputs that read another surface take a geometry record here, built by the same resolver as a boolean cutter.
function surfaceLoader(resolveCutter) {
  return surface => {
    if (!resolveCutter || typeof surface === 'string') throw new TypeError('A mesh edit field reads a surface given as a geometry record such as { "type": "terrain", ... }, not an id.');
    return createTriangleSurfaceIndex(triangulatedSurface(resolveCutter(surface)));
  };
}

function runEdit(current, edit, index, { resolveCutter, limits }) {
  const loadSurface = surfaceLoader(resolveCutter);
  const result = { op: edit.op };
  if (edit.name) result.name = edit.name;
  if (isModifierOperation(edit.op)) {
    let outcome;
    try {
      outcome = runModifierEdit(current, edit, limits);
    } catch (error) {
      throw editFailure(error, index, `${edit.op}`);
    }
    Object.assign(result, outcome.result);
    return { mesh: outcome.mesh, result };
  }
  if (edit.op === 'boolean') {
    if (!resolveCutter) throw new TypeError(`Mesh edit ${index} (boolean) needs a cutter resolver; recipe meshes provide one.`);
    let cutter;
    try {
      cutter = transformMesh(resolveCutter(edit.cutter), edit);
    } catch (error) {
      throw editFailure(error, index, `boolean cutter`);
    }
    const cutTag = `${edit.name}.cut`;
    let outcome;
    try {
      outcome = meshBoolean(current, cutter, edit.operation, { cutTag });
    } catch (error) {
      throw editFailure(error, index, `boolean ${edit.operation}`);
    }
    result.operation = edit.operation;
    result.tags = { [cutTag]: outcome.cutterFaces };
    return { mesh: outcome.mesh, result };
  }
  if (edit.op === 'merge_by_distance') {
    const merged = mergeByDistance(current, edit.distance);
    result.removedVertices = merged.removedVertices;
    result.removedFaces = merged.removedFaces;
    return { mesh: merged.mesh, result };
  }
  if (edit.op === 'loop_cut') {
    let outcome;
    try {
      outcome = loopCut(current, edit.edges, edit);
    } catch (error) {
      throw editFailure(error, index, `loop_cut`);
    }
    result.rings = outcome.rings;
    result.closedRings = outcome.closedRings;
    result.splitEdges = outcome.splitEdges;
    result.tags = tagSummary(outcome.mesh, edit.name);
    return { mesh: outcome.mesh, result };
  }
  if (edit.op === 'bevel') {
    let outcome;
    try {
      outcome = bevelEdges(current, edit.edges, edit);
    } catch (error) {
      throw editFailure(error, index, `bevel`);
    }
    result.edges = outcome.bevelEdges;
    result.width = outcome.width;
    result.profile = outcome.profile;
    if (outcome.profileClamped) result.profileClamped = true;
    if (outcome.clamped) result.clamped = true;
    result.tags = tagSummary(outcome.mesh, edit.name);
    return { mesh: outcome.mesh, result };
  }
  if (CUT_OPERATIONS.includes(edit.op) || RESHAPE_OPERATIONS.includes(edit.op)) {
    let outcome;
    try {
      outcome = CUT_OPERATIONS.includes(edit.op) ? runCutEdit(current, edit) : runReshapeEdit(current, edit);
    } catch (error) {
      throw editFailure(error, index, `${edit.op}`);
    }
    Object.assign(result, outcome.result);
    const tags = tagSummary(outcome.mesh, edit.name);
    if (Object.keys(tags).length) result.tags = tags;
    return { mesh: outcome.mesh, result };
  }
  if (edit.op === 'set_position' || edit.op === 'displace') {
    let outcome;
    try {
      outcome = edit.op === 'set_position' ? setPosition(current, edit, loadSurface) : displaceMesh(current, edit, loadSurface);
    } catch (error) {
      throw editFailure(error, index, `${edit.op}`);
    }
    result.movedVertices = outcome.movedVertices;
    return { mesh: outcome.mesh, result };
  }
  if (edit.op === 'vertex_group' || edit.op === 'vertex_color') {
    let outcome;
    try {
      outcome = edit.op === 'vertex_group' ? setVertexGroup(current, edit, loadSurface) : setVertexColor(current, edit, loadSurface);
    } catch (error) {
      throw editFailure(error, index, `${edit.op}`);
    }
    if (edit.op === 'vertex_group') {
      result.group = edit.name;
      result.assignedVertices = outcome.assignedVertices;
    } else {
      result.assignedCorners = outcome.assignedCorners;
    }
    return { mesh: outcome.mesh, result };
  }
  if (edit.op === 'sculpt' || edit.op === 'shrinkwrap') {
    let outcome;
    try {
      outcome = edit.op === 'sculpt' ? sculptMesh(current, edit) : runShrinkwrap(current, edit, resolveCutter);
    } catch (error) {
      throw editFailure(error, index, `${edit.op}`);
    }
    result.movedVertices = outcome.movedVertices;
    if (outcome.missedVertices) result.missedVertices = outcome.missedVertices;
    return { mesh: outcome.mesh, result };
  }
  if (edit.op === 'subdivide') {
    let subdivided;
    try {
      subdivided = subdivideMesh(current, { levels: edit.levels, crease: edit.crease, sharpness: edit.sharpness });
    } catch (error) {
      throw editFailure(error, index, `subdivide`);
    }
    result.levels = edit.levels;
    return { mesh: subdivided, result };
  }
  if (edit.op === 'decimate') {
    let outcome;
    try {
      outcome = decimateMesh(current, edit);
    } catch (error) {
      throw editFailure(error, index, `decimate`);
    }
    result.triangles = outcome.triangles;
    if (!outcome.reachedTarget) result.stoppedEarly = true;
    return { mesh: outcome.mesh, result };
  }
  if (edit.op === 'remesh') {
    let outcome;
    try {
      outcome = remeshMesh(current, edit);
    } catch (error) {
      throw editFailure(error, index, `remesh`);
    }
    result.voxelSize = Number(outcome.voxelSize.toPrecision(5));
    return { mesh: outcome.mesh, result };
  }
  if (edit.op === 'uv_unwrap') {
    let outcome;
    try {
      const unwrapped = runKernel('uvUnwrap', [current, edit], unwrapUv);
      outcome = { ...unwrapped, mesh: createMeshData(unwrapped.mesh) };
    } catch (error) {
      if (error instanceof KernelDeferred) {
        throw error;
      }
      throw editFailure(error, index, `uv_unwrap`);
    }
    result.islands = outcome.islands;
    result.seamEdges = outcome.seamEdges;
    result.cutEdges = outcome.cutEdges;
    result.chartEdges = outcome.chartEdges;
    result.flipped = outcome.flipped;
    result.areaDistortion = Number(outcome.areaDistortion.toFixed(4));
    result.utilization = Number(outcome.utilization.toFixed(4));
    return { mesh: outcome.mesh, result };
  }
  if (edit.op === 'uv_project' || edit.op === 'uv_pack') {
    let outcome;
    try {
      outcome = edit.op === 'uv_project' ? projectUv(current, edit) : packUvIslands(current, edit);
    } catch (error) {
      throw editFailure(error, index, edit.op);
    }
    result.islands = outcome.islands;
    return { mesh: outcome.mesh, result };
  }
  if (Object.hasOwn(GENERATORS, edit.op)) {
    const generated = GENERATORS[edit.op](current, edit);
    result.tags = tagSummary(generated, edit.name);
    return { mesh: generated, result };
  }
  let mask;
  try {
    mask = selectFaces(current, edit.select);
  } catch (error) {
    throw editFailure(error, index, `${edit.op}`);
  }
  const selected = countSelected(mask);
  if (selected === 0) throw editField(index, 'select', edit.select, 'a rule that matches at least one face, such as { "all": true } (check tags and counts with mesh_inspect)', RangeError);
  result.selected = selected;
  const editable = editMesh(current);
  let created = null;
  switch (edit.op) {
    case 'extrude_face_region':
      created = extrudeFaceRegion(editable, mask, edit);
      break;
    case 'extrude_individual':
      created = extrudeIndividual(editable, mask, edit);
      break;
    case 'inset_region':
    case 'inset_individual': {
      const inset = edit.op === 'inset_region' ? insetRegion(editable, mask, edit) : insetIndividual(editable, mask, edit);
      created = { capFaces: inset.capFaces, sideFaces: inset.sideFaces, sideTag: 'rim' };
      result.thickness = inset.thickness;
      if (inset.clamped) result.clamped = true;
      break;
    }
    case 'delete':
      result.deletedFaces = deleteFaces(editable, mask).deletedFaces;
      break;
    case 'flip_normals':
      flipFaces(editable, mask);
      break;
    case 'translate':
      result.movedVertices = translateFaces(editable, mask, edit).movedVertices;
      break;
    case 'transform_selection':
      result.movedVertices = transformFaces(editable, mask, edit).movedVertices;
      break;
    case 'tag':
      tagFaces(editable, Array.from(mask.keys()).filter(face => mask[face]), edit.name);
      result.tags = { [edit.name]: selected };
      break;
  }
  if (created) {
    const sideTag = `${edit.name}.${created.sideTag ?? 'side'}`;
    tagFaces(editable, created.capFaces, `${edit.name}.cap`);
    tagFaces(editable, created.sideFaces, sideTag);
    result.tags = { [`${edit.name}.cap`]: created.capFaces.length, [sideTag]: created.sideFaces.length };
  }
  return { mesh: meshData(editable), result };
}

const GENERATORS = Object.freeze({
  mirror: (mesh, edit) => mirrorMesh(mesh, edit),
  array: (mesh, edit) => arrayMesh(mesh, edit),
  solidify: (mesh, edit) => solidifyMesh(mesh, edit),
});

/** Face counts of the tags an edit named `name` created (tags starting with "<name>."). */
function tagSummary(mesh, name) {
  const summary = {};
  for (const [attributeName, attribute] of Object.entries(mesh.attributes.face)) {
    if (!attributeName.startsWith(`tag:${name}.`)) continue;
    let count = 0;
    for (let face = 0; face < mesh.faceCount; face++) count += attribute.data[face] ? 1 : 0;
    summary[attributeName.slice(4)] = count;
  }
  return summary;
}

/**
 * Run an edit log on MeshData. Returns the final mesh and one compact result per edit: how many faces it selected,
 * the tags it created (and their face counts) and the mesh size after it.
 * An edit that selects no faces throws, because silently doing nothing hides a wrong selection from the agent.
 */
export function applyMeshEdits(mesh, edits, { maxVertices = 250_000, maxFaces = 250_000, resolveCutter } = {}) {
  const normalized = normalizeMeshEdits(edits);
  const limits = { maxVertices, maxFaces };
  const results = [];
  let current = mesh;
  normalized.forEach((edit, index) => {
    checkArrayBudget(current, edit, limits, index);
    const outcome = runEdit(current, edit, index, { resolveCutter, limits });
    current = outcome.mesh;
    checkBudget(current, limits, index, edit.op);
    outcome.result.after = { vertices: current.vertexCount, faces: current.faceCount };
    results.push(outcome.result);
  });
  return { mesh: current, results };
}


/** Validate a modifier stack: nodes restricted to STACK_OPERATIONS, at most 16. */
export function normalizeMeshStack(stack) {
  if (!Array.isArray(stack)) throw new TypeError('stack must be an array.');
  if (stack.length > MAX_STACK_NODES) throw new RangeError(`A stack holds at most ${MAX_STACK_NODES} nodes.`);
  for (const [index, node] of stack.entries()) {
    if (!STACK_OPERATIONS.includes(node?.op)) throw new TypeError(`Stack node ${index} op must be one of ${STACK_OPERATIONS.join(', ')}.`);
  }
  // Stack nodes default their names from their own position, separately from the edit log.
  return normalizeMeshEdits(stack.map((node, index) => {
    if (!MESH_EDIT_OPERATIONS[node.op].fields.includes('name')) return node;
    return { ...node, name: node.name ?? `${node.op}-s${index + 1}` };
  }));
}

/**
 * Evaluate a modifier stack after the edits, non-destructively, as Blender's modifier stack does. With a cache
 * ({ get(key), set(key, value) }) and a key for the input, every prefix of the stack is cached, so changing a late
 * node reuses the earlier ones. Returns the mesh and one result per node, marked `cached` when reused.
 */
export function evaluateMeshStack(mesh, stack, { maxVertices = 250_000, maxFaces = 250_000, cache, cacheKey } = {}) {
  const normalized = normalizeMeshStack(stack);
  const limits = { maxVertices, maxFaces };
  const results = [];
  let current = mesh;
  let key = cacheKey;
  normalized.forEach((node, index) => {
    key = key === undefined ? undefined : `${key}|${JSON.stringify(node)}`;
    const hit = key === undefined ? undefined : cache?.get(key);
    let result;
    if (hit) {
      // The cache key holds no limits, so a result built under larger limits is checked again under these.
      checkBudget(hit.mesh, limits, index, node.op);
      current = hit.mesh;
      result = { ...hit.result, cached: true };
    } else {
      checkArrayBudget(current, node, limits, index);
      const outcome = runEdit(current, node, index, { limits });
      current = outcome.mesh;
      checkBudget(current, limits, index, node.op);
      outcome.result.after = { vertices: current.vertexCount, faces: current.faceCount };
      result = outcome.result;
      if (key !== undefined) cache?.set(key, { mesh: current, result });
    }
    results.push(result);
  });
  return { mesh: current, results };
}