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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(material-studio): refuse to persist a restyle that moved the rig
nirholas64f6043c90e9
diff --git a/api/_lib/material-studio-store.js b/api/_lib/material-studio-store.jsindex 38bfcbdbb..26e877ad3 100644--- a/api/_lib/material-studio-store.js+++ b/api/_lib/material-studio-store.js@@ -41,6 +41,28 @@ 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;@@ -470,6 +492,11 @@ export async function restyleMaterialFromInstruction({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);@@ -490,6 +517,7 @@ export async function restyleMaterialFromInstruction({bytes: persisted.bytes,lineage,activeIndex: lineage.length - 1,+ preserve: { kinds: RETEXTURE_PRESERVE_KINDS, verified: true },};}@@ -550,6 +578,9 @@ export async function generateSeededVariants({};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',});@@ -575,5 +606,6 @@ export async function generateSeededVariants({variants: results,lineage,activeIndex: sharedParentIndex,+ preserve: { kinds: RETEXTURE_PRESERVE_KINDS, verified: true },};}diff --git a/api/material-studio.js b/api/material-studio.jsindex f4515f1b6..ecb1ddb3a 100644--- a/api/material-studio.js+++ b/api/material-studio.js@@ -88,14 +88,15 @@ const discovery = wrap(async (req, res) => {query: '?action=restyle',body: '{ glb_url, instruction, material_index?, parent_lineage?, parent_index? }',returns:- '{ glbUrl, sourceGlbUrl, instruction, factors, materialsEdited, lineage, activeIndex }',+ '{ glbUrl, sourceGlbUrl, instruction, factors, materialsEdited, lineage, activeIndex, preserve }',},variants: {method: 'POST',query: '?action=variants',body: '{ glb_url, preset?, seed?, count?, material_index?, parent_lineage?, parent_index? }',presets: MATERIAL_PRESET_NAMES,- returns: '{ variants: [{ glbUrl, label, seed, config, lineageIndex }], lineage, activeIndex }',+ returns:+ '{ variants: [{ glbUrl, label, seed, config, lineageIndex }], lineage, activeIndex, preserve }',},},lineage:@@ -103,6 +104,11 @@ const discovery = wrap(async (req, res) => {'(the same shape refine_model uses). Pass the returned `lineage` array back in as ' +'`parent_lineage` on the next call to extend one thread; add `parent_index` to branch off ' +'an earlier version instead of the latest.',+ preserve:+ 'Every restyle/variants response includes `preserve: { kinds, verified }`: the output GLB ' ++ 'was diffed against its source with @three-ws/glb-diff and confirmed topology, UVs, ' ++ 'skeleton, skin and clips are unchanged. A response is only ever sent when verified is true; ' ++ 'a violation throws before the output is persisted.',web: 'https://three.ws/restyle',});});diff --git a/tests/api/material-studio-store.test.js b/tests/api/material-studio-store.test.jsindex b38949181..28992bff9 100644--- a/tests/api/material-studio-store.test.js+++ b/tests/api/material-studio-store.test.js@@ -137,6 +137,48 @@ describe('restyleMaterialFromInstruction', () => {expect(result.activeIndex).toBe(1);});+ it('retextures a rigged, animated GLB and proves skeleton/skin/UVs/clips are unchanged (work order 078)', async () => {+ // fox.glb is a rigged, three-clip avatar (1 skin, animations Survey/Walk/Run),+ // so a real restyle through it is the actual Definition-of-Done proof, not a+ // synthetic triangle: this is the SAME fixture every other test in this file+ // restyles, confirmed here against the real glb-diff engine instead of a mock.+ const { restyleMaterialFromInstruction } = await import('../../api/_lib/material-studio-store.js');+ const { describeModel, diffDescriptions } = await import('@three-ws/glb-diff');++ const result = await restyleMaterialFromInstruction({ glbUrl: FIXTURE_URL, instruction: 'make it chrome' });++ expect(result.preserve).toEqual({+ kinds: ['topology', 'uv', 'skeleton', 'skin', 'clips'],+ verified: true,+ });++ // Independent proof, outside material-studio-store's own verifyPreserved+ // call: diff the real fixture bytes against the real persisted output and+ // confirm topology/uv/skinWeights never show up as changed mesh fields, the+ // skin resource (joints, bind pose) is untouched, and no animation changed.+ // result.bytes is the byte COUNT (validateAndPersistGlb's return shape);+ // the actual persisted bytes are what the mocked putObject captured.+ const before = await describeModel(fixtureBytes);+ const after = await describeModel(uploadedObjects[0].body);+ const changes = diffDescriptions(before, after);++ const meshFields = changes.sections.meshes.modified.flatMap((m) => m.changes.map((c) => c.field));+ expect(meshFields).not.toContain('topology');+ expect(meshFields).not.toContain('uv');+ expect(meshFields).not.toContain('skinWeights');+ expect(changes.sections.skins.modified).toHaveLength(0);+ expect(changes.sections.skins.removed).toHaveLength(0);+ expect(changes.sections.animations.modified).toHaveLength(0);+ expect(changes.sections.animations.removed).toHaveLength(0);++ // And the restyle still did something real: the material actually changed.+ // (meshFields may still list 'geometry'/normals: re-serializing through+ // glTF-Transform can legitimately re-bake NORMAL/TANGENT precision, which+ // describe.js's TOPOLOGY_SEMANTICS deliberately excludes for exactly this+ // reason. topology/uv/skinWeights are the fields that must never appear.)+ expect(changes.sections.materials.modified.length).toBeGreaterThan(0);+ });+it('extends a caller-supplied parent_lineage instead of starting fresh', async () => {const { restyleMaterialFromInstruction } = await import('../../api/_lib/material-studio-store.js');const parentLineage = [@@ -262,6 +304,7 @@ describe('generateSeededVariants', () => {expect(a.variants.map((v) => v.config.color)).toEqual(b.variants.map((v) => v.config.color));expect(a.variants.map((v) => v.seed)).toEqual(b.variants.map((v) => v.seed));for (const v of a.variants) expect(v.glbUrl).toMatch(persistedGlbUrl('material-studio/variants'));+ expect(a.preserve).toEqual({ kinds: ['topology', 'uv', 'skeleton', 'skin', 'clips'], verified: true });});it('fans every variant off the SAME shared parent rather than chaining them', async () => {