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.

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.js
index 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.js
index 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.js
index 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 () => {