Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

27.2 KB
Raw Blame
// Material Studio — server core: AI PBR restyle + seeded colorway variants +
// durable persistence for arbitrary (non-avatar) GLBs.
//
// Generalizes the Avatar Studio idea — "re-skin what you already have" — to any
// GLB. Two real capabilities live here, both non-destructive (the source GLB is
// never mutated; every call reads fresh bytes and writes a NEW object):
//
//   1. restyleMaterialFromInstruction — "make it chrome" / "wooden" / "cyberpunk"
//      → IBM Granite (watsonx.ai) proposes a glTF 2.0 PBR material (base color,
//      metalness, roughness, emissive) from the description, then @gltf-transform
//      applies those factors onto the target material(s) and re-exports. Mesh
//      geometry and UVs are never touched — only material factors — so the
//      output is guaranteed shape-identical to the input.
//   2. generateSeededVariants — fan one preset out into N reproducible colorway
//      variants using @three-ws/viewer-presets' materialVariants() (mulberry32
//      seeded PRNG — same base + seed always produces byte-identical configs).
//
// Both share one persistence path (validateAndPersistGlb) so every output is a
// real, gltf-validator-checked, durably-stored https URL — never a blob, never
// a mock. One implementation; the web Restyle Studio page (/restyle) calls it
// over api/material-studio.js for free (rate-limited), and the restyle_material
// MCP tool (mcp-server/src/tools/restyle-material.js) calls the SAME HTTP
// endpoint as a thin client, matching the forge_free / refine_model "one core,
// two transports" convention already used across the 3D stack.
//
// Both operations also record an immutable parent → child version lineage using
// the SAME lineage core refine_model uses (mcp-server/src/tools/_lineage.js) —
// a restyle or a variant fan-out is just another kind of version, not a special
// case. Pass the `lineage` array a previous call returned back in as
// `parentLineage` to extend one thread; omit it to start fresh, rooted at the
// source GLB. This is what makes restyle non-destructive in the durable sense
// (not just "Reset in the browser"): every version is a real, separately
// addressable asset, and the thread is exactly the shape prompt 09's remix
// bazaar already consumes for refine_model lineages.

import { randomUUID } from 'node:crypto';
import { putObject, publicUrl } from './r2.js';
import { assertPublicHttpsUrl } from './ssrf.js';
import { fetchSafePublicUrlPinned, MaxBytesExceededError } from './ssrf-guard.js';
import { watsonxConfig, watsonxChatComplete } from './watsonx.js';
import { llmComplete } from './llm.js';
import { materialVariants, materialPreset, MATERIAL_PRESET_NAMES } from '@three-ws/viewer-presets';
import { seedLineage, appendVersion, branchFrom, buildLineageChain } from '../../mcp-server/src/tools/_lineage.js';
import { verifyPreserved, PreserveViolationError, PRESERVE_KINDS } from './preserve-contract.js';

// A material restyle or colorway variant only ever calls a Material setter
// (applyFactorsToDoc above), never touches a Mesh/Primitive/Skin/Animation
// property, so it declares the full preserve contract: every edit here must
// come back with topology, UVs, skeleton, skin and clips bit-for-bit
// unchanged, or the edit is a bug, not a successful restyle.
const RETEXTURE_PRESERVE_KINDS = PRESERVE_KINDS;

// Wraps verifyPreserved so a violation surfaces through the SAME error path
// every other Material Studio failure uses (api/material-studio.js only knows
// how to translate MaterialStudioError into an HTTP response).
async function assertPreserved(beforeBytes, afterBytes, kinds, label) {
	try {
		await verifyPreserved(beforeBytes, afterBytes, kinds, { label });
	} catch (err) {
		if (err instanceof PreserveViolationError) {
			throw new MaterialStudioError(err.message, { status: err.status, code: err.code });
		}
		throw err;
	}
}

const MAX_SOURCE_GLB_BYTES = 64 * 1024 * 1024;
const MAX_VARIANT_COUNT = 12;
const FETCH_TIMEOUT_MS = 30_000;

export class MaterialStudioError extends Error {
	constructor(message, { status = 500, code = 'material_studio_error' } = {}) {
		super(message);
		this.name = 'MaterialStudioError';
		this.status = status;
		this.code = code;
	}
}

function clamp01(n, fallback = 0) {
	const v = Number(n);
	return Number.isFinite(v) ? Math.min(1, Math.max(0, v)) : fallback;
}

// glTF binary magic — first 4 bytes are ASCII "glTF". Mirrors
// api/_lib/pipeline-stage.js's isGlbMagic so a bad upload/fetch fails the same
// way everywhere in the pipeline.
function isGlbMagic(bytes) {
	return (
		bytes?.length >= 12 &&
		bytes[0] === 0x67 &&
		bytes[1] === 0x6c &&
		bytes[2] === 0x54 &&
		bytes[3] === 0x46
	);
}

function stripJsonFence(text) {
	const raw = String(text || '').trim();
	return raw.startsWith('```') ? raw.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '') : raw;
}

async function fetchGlbBytes(url) {
	let resp;
	try {
		// Pinned guard fetch: the URL is validated upstream, but a validated
		// host could still redirect to an internal address, and validation
		// alone leaves a DNS-rebinding window. The streaming cap replaces the
		// old post-hoc length check.
		resp = await fetchSafePublicUrlPinned(
			url,
			{ signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) },
			{ maxBytes: MAX_SOURCE_GLB_BYTES },
		);
	} catch (err) {
		if (err instanceof MaxBytesExceededError) {
			throw new MaterialStudioError(`source GLB exceeds the ${MAX_SOURCE_GLB_BYTES}-byte limit`, {
				status: 413,
				code: 'source_too_large',
			});
		}
		throw new MaterialStudioError(`could not fetch glb_url: ${err.message}`, {
			status: 502,
			code: 'fetch_failed',
		});
	}
	if (!resp.ok) {
		throw new MaterialStudioError(`glb_url returned ${resp.status}`, {
			status: resp.status === 404 ? 404 : 502,
			code: 'fetch_failed',
		});
	}
	const buf = Buffer.from(await resp.arrayBuffer());
	if (!buf.length) throw new MaterialStudioError('glb_url is empty', { status: 502, code: 'empty_source' });
	if (!isGlbMagic(buf)) {
		throw new MaterialStudioError('glb_url is not a binary glTF (.glb) — its bytes lack the "glTF" magic header', {
			status: 415,
			code: 'unsupported_media_type',
		});
	}
	return buf;
}

// Validate a caller-supplied glb_url (scheme + SSRF + DNS) before ANY fetch.
export async function validateGlbUrl(raw, field = 'glb_url') {
	const value = typeof raw === 'string' ? raw.trim() : '';
	if (!value) throw new MaterialStudioError(`${field} is required`, { status: 400, code: 'missing_url' });
	try {
		return await assertPublicHttpsUrl(value);
	} catch (err) {
		throw new MaterialStudioError(`${field} rejected: ${err.message}`, { status: 400, code: 'invalid_url' });
	}
}

// ── glTF-Transform document I/O (lazy — keeps this module's static import cost
// low for the (more common) code paths that never touch a document, e.g. the
// discovery GET). ────────────────────────────────────────────────────────────

// EXT_meshopt_compression is in ALL_EXTENSIONS, but glTF-Transform still needs
// the codec injected before it can read or write one, and most three.ws avatars
// ship compressed. Without it every compressed source failed here as
// "source GLB failed to parse", which reads like a corrupt upload and is not.
async function meshoptIO() {
	const [{ NodeIO }, { ALL_EXTENSIONS }, { MeshoptDecoder, MeshoptEncoder }] = await Promise.all([
		import('@gltf-transform/core'),
		import('@gltf-transform/extensions'),
		import('meshoptimizer'),
	]);
	await Promise.all([MeshoptDecoder.ready, MeshoptEncoder.ready]);
	return new NodeIO()
		.registerExtensions(ALL_EXTENSIONS)
		.registerDependencies({ 'meshopt.decoder': MeshoptDecoder, 'meshopt.encoder': MeshoptEncoder });
}

async function loadDocument(bytes) {
	const io = await meshoptIO();
	try {
		return await io.readBinary(new Uint8Array(bytes));
	} catch (err) {
		throw new MaterialStudioError(`source GLB failed to parse: ${err.message}`, {
			status: 415,
			code: 'invalid_glb',
		});
	}
}

async function writeAndValidate(doc) {
	const io = await meshoptIO();
	const bytes = await io.writeBinary(doc);

	const { validateBytes } = await import('gltf-validator');
	const report = await validateBytes(bytes).catch((err) => {
		throw new MaterialStudioError(`output GLB failed validation: ${err.message}`, {
			status: 502,
			code: 'validation_threw',
		});
	});
	const numErrors = report?.issues?.numErrors ?? 0;
	if (numErrors > 0) {
		const first = report.issues.messages?.find((m) => m.severity === 0)?.message;
		throw new MaterialStudioError(
			`restyled GLB failed glTF validation (${numErrors} error${numErrors === 1 ? '' : 's'})${first ? `: ${first}` : ''}`,
			{ status: 502, code: 'invalid_output' },
		);
	}
	return bytes;
}

// Apply a flat PBR factor set onto every material in the doc (or just
// `materialIndex` when given). Geometry, accessors, and UVs are untouched —
// this only ever calls the Material setters, never the Mesh/Primitive ones —
// which is what guarantees "preserve mesh + UVs" through a restyle.
//
// `factors` may additionally carry the measured-value extension fields
// (clearcoatFactor/clearcoatRoughnessFactor, transmissionFactor, ior,
// sheenColorFactor/sheenRoughnessFactor) — these are real KHR_materials_*
// extensions, lazily attached to the document only when a factor set
// actually uses them, so a plain restyle never grows a document with unused
// extension declarations.
async function applyFactorsToDoc(doc, factors, materialIndex) {
	const materials = doc.getRoot().listMaterials();
	if (!materials.length) {
		throw new MaterialStudioError('source GLB has no materials to restyle', {
			status: 422,
			code: 'no_materials',
		});
	}
	const targets =
		Number.isInteger(materialIndex) && materials[materialIndex] ? [materials[materialIndex]] : materials;

	const hasClearcoat = factors.clearcoatFactor != null || factors.clearcoatRoughnessFactor != null;
	const hasTransmission = factors.transmissionFactor != null;
	const hasIor = factors.ior != null;
	const hasSheen = Array.isArray(factors.sheenColorFactor) || factors.sheenRoughnessFactor != null;

	let KHRMaterialsClearcoat, KHRMaterialsTransmission, KHRMaterialsIOR, KHRMaterialsSheen;
	if (hasClearcoat || hasTransmission || hasIor || hasSheen) {
		// Extension classes import lazily — the (more common) factor-only
		// restyle path never pays this cost.
		({ KHRMaterialsClearcoat, KHRMaterialsTransmission, KHRMaterialsIOR, KHRMaterialsSheen } = await import(
			'@gltf-transform/extensions'
		));
	}
	let clearcoatExt, transmissionExt, iorExt, sheenExt;

	for (const mat of targets) {
		if (Array.isArray(factors.baseColorFactor) && factors.baseColorFactor.length === 4) {
			mat.setBaseColorFactor(factors.baseColorFactor.map((v, i) => (i === 3 ? clamp01(v, 1) : clamp01(v))));
		} else if (Array.isArray(factors.baseColorFactor) && factors.baseColorFactor.length === 3) {
			mat.setBaseColorFactor([...factors.baseColorFactor.map((v) => clamp01(v)), mat.getBaseColorFactor()[3] ?? 1]);
		}
		if (factors.metallicFactor != null) mat.setMetallicFactor(clamp01(factors.metallicFactor));
		if (factors.roughnessFactor != null) mat.setRoughnessFactor(clamp01(factors.roughnessFactor, 0.5));
		if (Array.isArray(factors.emissiveFactor) && factors.emissiveFactor.length === 3) {
			mat.setEmissiveFactor(factors.emissiveFactor.map((v) => clamp01(v)));
		}
		if (factors.name) mat.setName(factors.name);

		if (hasClearcoat) {
			clearcoatExt = clearcoatExt || doc.createExtension(KHRMaterialsClearcoat);
			const clearcoat = clearcoatExt.createClearcoat();
			if (factors.clearcoatFactor != null) clearcoat.setClearcoatFactor(clamp01(factors.clearcoatFactor));
			if (factors.clearcoatRoughnessFactor != null) {
				clearcoat.setClearcoatRoughnessFactor(clamp01(factors.clearcoatRoughnessFactor));
			}
			mat.setExtension('KHR_materials_clearcoat', clearcoat);
		}
		if (hasTransmission) {
			transmissionExt = transmissionExt || doc.createExtension(KHRMaterialsTransmission);
			const transmission = transmissionExt.createTransmission().setTransmissionFactor(clamp01(factors.transmissionFactor));
			mat.setExtension('KHR_materials_transmission', transmission);
		}
		if (hasIor) {
			iorExt = iorExt || doc.createExtension(KHRMaterialsIOR);
			const ior = iorExt.createIOR().setIOR(Math.min(2.333, Math.max(1, Number(factors.ior) || 1.5)));
			mat.setExtension('KHR_materials_ior', ior);
		}
		if (hasSheen) {
			sheenExt = sheenExt || doc.createExtension(KHRMaterialsSheen);
			const sheen = sheenExt.createSheen();
			if (Array.isArray(factors.sheenColorFactor) && factors.sheenColorFactor.length === 3) {
				sheen.setSheenColorFactor(factors.sheenColorFactor.map((v) => clamp01(v)));
			}
			if (factors.sheenRoughnessFactor != null) sheen.setSheenRoughnessFactor(clamp01(factors.sheenRoughnessFactor));
			mat.setExtension('KHR_materials_sheen', sheen);
		}
	}
	return targets.length;
}

function hexToFactor(hex, fallback = [0.6, 0.6, 0.6]) {
	const m = /^#?([0-9a-f]{6})$/i.exec(String(hex || '').trim());
	if (!m) return fallback;
	const int = parseInt(m[1], 16);
	return [((int >> 16) & 255) / 255, ((int >> 8) & 255) / 255, (int & 255) / 255];
}

// ── Lineage ─────────────────────────────────────────────────────────────────

// Resolve the starting lineage: extend the caller-supplied one (validated
// structurally — contiguous indices, single root, no cycles — with
// buildLineageChain), or seed a fresh one rooted at the source GLB. A malformed
// array (buggy client, stale/tampered state) falls back to a fresh lineage
// rather than corrupting history — mirrors handleRefineModel's contract exactly
// (api/_mcp-studio/tools.js) so both "kinds" of 3D versioning behave the same.
export function resolveBaseLineage(rootGlbUrl, parentLineage) {
	const fresh = () => seedLineage({ glbUrl: rootGlbUrl });
	if (!Array.isArray(parentLineage) || parentLineage.length === 0) return fresh();
	const rehydrated = parentLineage.map((v, i) => ({
		index: Number.isInteger(v?.index) ? v.index : i,
		parentIndex: v?.parentIndex ?? (i > 0 ? i - 1 : null),
		glbUrl: v?.glbUrl,
		viewerUrl: v?.viewerUrl || null,
		prompt: v?.prompt || null,
		instruction: v?.instruction || null,
		refKind: v?.refKind || (i === 0 ? 'origin' : 'text'),
	}));
	return buildLineageChain(rehydrated).ok ? rehydrated : fresh();
}

// Branch off an earlier version instead of the lineage's leaf. An out-of-range
// index falls back to `undefined` (appendVersion then defaults to the leaf)
// rather than throwing — a stale parent_index should never fail the call.
export function resolveParentIndex(baseLineage, parentIndex) {
	if (!Number.isInteger(parentIndex)) return undefined;
	try {
		return branchFrom(baseLineage, parentIndex);
	} catch {
		return undefined;
	}
}

// ── Persistence ─────────────────────────────────────────────────────────────

// Validate GLB bytes (magic + gltf-validator) and mirror into R2 under
// material-studio/<uuid>.glb. Every function below funnels through this so
// every URL this module ever hands back is a real, checked, durable asset.
export async function validateAndPersistGlb(bytes, { keyPrefix = 'material-studio' } = {}) {
	if (!bytes?.length) throw new MaterialStudioError('no GLB bytes to persist', { status: 400, code: 'empty_input' });
	if (bytes.length > MAX_SOURCE_GLB_BYTES) {
		throw new MaterialStudioError(`GLB is ${bytes.length} bytes; max is ${MAX_SOURCE_GLB_BYTES}`, {
			status: 413,
			code: 'too_large',
		});
	}
	if (!isGlbMagic(bytes)) {
		throw new MaterialStudioError('not a binary glTF (.glb) — bytes lack the "glTF" magic header', {
			status: 415,
			code: 'unsupported_media_type',
		});
	}
	const { validateBytes } = await import('gltf-validator');
	const report = await validateBytes(new Uint8Array(bytes)).catch((err) => {
		throw new MaterialStudioError(`GLB failed validation: ${err.message}`, { status: 422, code: 'validation_threw' });
	});
	const numErrors = report?.issues?.numErrors ?? 0;
	if (numErrors > 0) {
		throw new MaterialStudioError(`GLB failed glTF validation (${numErrors} error${numErrors === 1 ? '' : 's'})`, {
			status: 422,
			code: 'invalid_glb',
		});
	}
	const key = `${keyPrefix}/${randomUUID()}.glb`;
	await putObject({ key, body: bytes, contentType: 'model/gltf-binary', metadata: { source: 'material-studio' } });
	return { url: publicUrl(key), bytes: bytes.length, key };
}

// ── 1. AI restyle: instruction → PBR factors → applied + persisted GLB ──────

// A full PBR answer (name, three factor triples, the optional clearcoat /
// transmission / sheen blocks, and a notes sentence) measures ~300 tokens of
// JSON; 400 leaves headroom so a slightly more verbose model returns closing
// braces instead of a fragment that fails the JSON.parse below.
const MATERIAL_AUTHOR_MAX_TOKENS = 400;
// Overall budget across the whole fallback chain, matching the prompt
// director's. A restyle is interactive: the caller is watching a button.
const MATERIAL_AUTHOR_TIMEOUT_MS = 20_000;

// Ask IBM Granite (watsonx.ai) for a glTF PBR material from a plain-language
// description. Same system-prompt shape as the generate_material MCP tool
// (api/_mcp3d/tools/studio.js), factored out here so Material Studio doesn't
// duplicate the watsonx wiring — reuses watsonxConfig/watsonxChatComplete
// directly rather than the tool wrapper (which carries MCP-only concerns).
export async function generateMaterialFactorsFromInstruction(instruction) {
	const trimmed = typeof instruction === 'string' ? instruction.trim() : '';
	if (trimmed.length < 2) {
		throw new MaterialStudioError('instruction must be at least 2 characters', {
			status: 400,
			code: 'invalid_instruction',
		});
	}
	const system =
		'You are a 3D material author. Given a short restyle instruction (e.g. "make it chrome", "wooden", ' +
		'"cyberpunk neon", "car paint", "frosted glass"), return ONLY a valid JSON object describing a glTF 2.0 ' +
		'PBR material with keys: "name" (string), "baseColorFactor" ([r,g,b] 0-1), "metallicFactor" (0-1), ' +
		'"roughnessFactor" (0-1), "emissiveFactor" ([r,g,b] 0-1, [0,0,0] unless the instruction implies glow/light), ' +
		'and "notes" (one short sentence on the look). Additionally, ONLY when the instruction implies these real ' +
		'physical effects, include: "clearcoatFactor" (0-1) + "clearcoatRoughnessFactor" (0-1) for a lacquered/' +
		'wet/car-paint/varnished look; "transmissionFactor" (0-1) + "ior" (1-2.333, real glass is ~1.45, water ' +
		'~1.33, diamond ~2.42) for see-through glass/liquid/crystal; "sheenColorFactor" ([r,g,b] 0-1) + ' +
		'"sheenRoughnessFactor" (0-1) for fabric/velvet/skin-like soft grazing highlights. Omit any key that does ' +
		'not apply — do not invent clearcoat/transmission/sheen for a plain metal or plastic instruction. ' +
		'No markdown, no prose outside the JSON.';
	// Two-rung author chain. IBM Granite (watsonx) leads where it is configured
	// because its factors are what the shipped presets were tuned against, and the
	// shared free-first chain (llmComplete: the same ladder forge-enhance and the
	// prompt director ride) backs it up. Before this, an unset WATSONX_API_KEY made
	// restyle a hard 503 on any deployment without an IBM key, which is exactly how
	// production served a dead "AI restyle is not configured" button while a healthy
	// LLM chain sat one call away. Neither rung is required; only an exhausted chain
	// is an error.
	let result = null;
	let lastError = null;
	const cfg = watsonxConfig();
	if (cfg.configured) {
		try {
			result = await watsonxChatComplete(cfg, {
				messages: [
					{ role: 'system', content: system },
					{ role: 'user', content: trimmed },
				],
				maxTokens: MATERIAL_AUTHOR_MAX_TOKENS,
				temperature: 0.4,
			});
		} catch (err) {
			lastError = err;
			result = null;
		}
	}
	if (!result?.text) {
		try {
			result = await llmComplete({
				system,
				user: trimmed,
				maxTokens: MATERIAL_AUTHOR_MAX_TOKENS,
				timeoutMs: MATERIAL_AUTHOR_TIMEOUT_MS,
				track: { tool: 'material-studio-restyle' },
			});
		} catch (err) {
			lastError = err;
			result = null;
		}
	}
	if (!result?.text) {
		throw new MaterialStudioError(
			`AI restyle could not reach a language model: ${lastError?.message || 'no provider is configured on this deployment'}`,
			{ status: 503, code: 'no_provider' },
		);
	}
	let parsed;
	try {
		parsed = JSON.parse(stripJsonFence(result.text));
	} catch {
		throw new MaterialStudioError('AI restyle model did not return usable material JSON', {
			status: 502,
			code: 'bad_model_output',
		});
	}
	return {
		name: typeof parsed.name === 'string' ? parsed.name.slice(0, 100) : trimmed.slice(0, 60),
		baseColorFactor: Array.isArray(parsed.baseColorFactor) ? parsed.baseColorFactor.slice(0, 3) : null,
		metallicFactor: typeof parsed.metallicFactor === 'number' ? parsed.metallicFactor : null,
		roughnessFactor: typeof parsed.roughnessFactor === 'number' ? parsed.roughnessFactor : null,
		emissiveFactor: Array.isArray(parsed.emissiveFactor) ? parsed.emissiveFactor.slice(0, 3) : [0, 0, 0],
		clearcoatFactor: typeof parsed.clearcoatFactor === 'number' ? parsed.clearcoatFactor : null,
		clearcoatRoughnessFactor: typeof parsed.clearcoatRoughnessFactor === 'number' ? parsed.clearcoatRoughnessFactor : null,
		transmissionFactor: typeof parsed.transmissionFactor === 'number' ? parsed.transmissionFactor : null,
		ior: typeof parsed.ior === 'number' ? parsed.ior : null,
		sheenColorFactor: Array.isArray(parsed.sheenColorFactor) ? parsed.sheenColorFactor.slice(0, 3) : null,
		sheenRoughnessFactor: typeof parsed.sheenRoughnessFactor === 'number' ? parsed.sheenRoughnessFactor : null,
		notes: typeof parsed.notes === 'string' ? parsed.notes.slice(0, 300) : null,
		model: result.model,
		instruction: trimmed,
	};
}

// Full pipeline: instruction → factors → fetch source → apply → validate →
// persist. Returns the restyled GLB URL plus the factors that were applied, so
// a browser caller (which already has the model loaded) can also apply the
// SAME factors live to its in-memory THREE.Material for an instant preview
// while the durable copy is still uploading.
export async function restyleMaterialFromInstruction({
	glbUrl,
	instruction,
	materialIndex,
	parentLineage,
	parentIndex,
}) {
	const safeUrl = await validateGlbUrl(glbUrl);
	const factors = await generateMaterialFactorsFromInstruction(instruction);
	const sourceBytes = await fetchGlbBytes(safeUrl);
	const doc = await loadDocument(sourceBytes);
	const materialsEdited = await applyFactorsToDoc(doc, factors, materialIndex);
	const outBytes = await writeAndValidate(doc);
	// A restyle only ever calls Material setters, so it declares the full
	// preserve contract. Verified BEFORE persisting: an edit that somehow moved
	// geometry/skin/clip data is a bug, and a bug must never reach a URL the
	// caller can treat as a successful restyle.
	await assertPreserved(sourceBytes, outBytes, RETEXTURE_PRESERVE_KINDS, 'material-studio restyle');
	const persisted = await validateAndPersistGlb(Buffer.from(outBytes), { keyPrefix: 'material-studio/restyle' });

	const baseLineage = resolveBaseLineage(safeUrl, parentLineage);
	const resolvedParentIndex = resolveParentIndex(baseLineage, parentIndex);
	const lineage = appendVersion(baseLineage, {
		glbUrl: persisted.url,
		instruction: factors.instruction,
		refKind: 'restyle',
		...(resolvedParentIndex !== undefined ? { parentIndex: resolvedParentIndex } : {}),
	});

	return {
		glbUrl: persisted.url,
		sourceGlbUrl: safeUrl,
		instruction: factors.instruction,
		factors,
		materialsEdited,
		bytes: persisted.bytes,
		lineage,
		activeIndex: lineage.length - 1,
		preserve: { kinds: RETEXTURE_PRESERVE_KINDS, verified: true },
	};
}

// ── 2. Seeded colorway variants ──────────────────────────────────────────────

// Fan one preset (or the model's current look, approximated by `preset`) out
// into `count` reproducible variants and persist each as its own GLB. Same
// base + seed always yields byte-identical factor sets (materialVariants'
// mulberry32 PRNG) and, downstream, byte-identical GLBs — reproducible in the
// literal sense, not just "looks similar."
export async function generateSeededVariants({
	glbUrl,
	preset = 'chrome',
	seed = 0,
	count = 6,
	materialIndex,
	parentLineage,
	parentIndex,
}) {
	if (!MATERIAL_PRESET_NAMES.includes(preset)) {
		throw new MaterialStudioError(`unknown preset "${preset}" — known: ${MATERIAL_PRESET_NAMES.join(', ')}`, {
			status: 400,
			code: 'invalid_preset',
		});
	}
	const safeUrl = await validateGlbUrl(glbUrl);
	const n = Math.max(1, Math.min(MAX_VARIANT_COUNT, Number(count) || 6));
	const seedNum = Number.isInteger(seed) ? seed >>> 0 : 0;
	const base = materialPreset(preset);
	const variants = materialVariants(base, { seed: seedNum, count: n });
	const sourceBytes = await fetchGlbBytes(safeUrl);

	// Every variant is an independent sibling branching off the SAME parent (the
	// source model) — resolve that shared parent once, up front, so appending
	// variant 2 never accidentally chains off variant 1.
	const baseLineage = resolveBaseLineage(safeUrl, parentLineage);
	const sharedParentIndex = resolveParentIndex(baseLineage, parentIndex) ?? baseLineage.length - 1;
	let lineage = baseLineage;

	const results = [];
	for (const variant of variants) {
		// Reload the document fresh from the untouched source bytes for every
		// variant — applying variant N onto a doc already mutated by variant
		// N-1 would compound edits instead of fanning out N independent looks.
		const doc = await loadDocument(sourceBytes);
		const factors = {
			baseColorFactor: hexToFactor(variant.config.color),
			metallicFactor: variant.config.metalness,
			roughnessFactor: variant.config.roughness,
			emissiveFactor: variant.config.emissive ? hexToFactor(variant.config.emissive, [0, 0, 0]) : [0, 0, 0],
			name: variant.label,
			clearcoatFactor: variant.config.clearcoat ?? null,
			clearcoatRoughnessFactor: variant.config.clearcoatRoughness ?? null,
			transmissionFactor: variant.config.transmission ?? null,
			ior: variant.config.ior ?? null,
			sheenColorFactor: variant.config.sheenColor ? hexToFactor(variant.config.sheenColor, [0, 0, 0]) : null,
			sheenRoughnessFactor: variant.config.sheenRoughness ?? null,
		};
		await applyFactorsToDoc(doc, factors, materialIndex);
		const outBytes = await writeAndValidate(doc);
		// Every variant branches off the SAME untouched sourceBytes, so each one
		// is checked against that shared source, not against the previous variant.
		await assertPreserved(sourceBytes, outBytes, RETEXTURE_PRESERVE_KINDS, `material-studio variant "${variant.label}"`);
		const persisted = await validateAndPersistGlb(Buffer.from(outBytes), {
			keyPrefix: 'material-studio/variants',
		});
		lineage = appendVersion(lineage, {
			glbUrl: persisted.url,
			instruction: variant.label,
			refKind: 'variant',
			parentIndex: sharedParentIndex,
		});
		results.push({
			glbUrl: persisted.url,
			label: variant.label,
			seed: variant.seed,
			config: variant.config,
			lineageIndex: lineage.length - 1,
		});
	}
	return {
		sourceGlbUrl: safeUrl,
		preset,
		seed: seedNum,
		count: n,
		variants: results,
		lineage,
		activeIndex: sharedParentIndex,
		preserve: { kinds: RETEXTURE_PRESERVE_KINDS, verified: true },
	};
}