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
docs(restyle): document the preserve-contract verification and diff links
nirholas22aa23aa668b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex dcf4632ec..4d5dad88a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **Animation Studio: trim, loop-blend, and save any generated clip to your library**: The Animation Studio's prompt-to-clip flow (type a prompt, generate motion on the self-hosted GPU worker, preview it retargeted onto the loaded avatar) now has an editing and persistence half. The transport grows trim start/end inputs, a loop-blend duration field, and a loop toggle, all recomputed through a non-destructive edit path so the live preview, the GLB export, and the saved clip always agree on the current edit. A Save to library button collects a name and visibility and posts the canonical, pre-retarget clip to the shared clip library, so it plays back correctly on any future rig, not just the avatar it was previewed on. A separate bug that crashed every generated clip's playback the moment it reached the browser (AnimationClip.parse() expected userData as a JSON string, the server was sending an object) is also fixed. (`/pose`) `[feature, fix]`- **Engine QA: a free real-time-engine fitness grade, plus real LOD chains**: A new free grade answers the question a game engine's import step asks that neither glTF validation nor simulation readiness does: draw calls, material count, texel density against the mesh's real-world size, a per-level triangle budget for a LOD chain, and whether the mesh is cheap and closed enough to use as its own physics collider. GET/POST /api/3d/engine-qa grades any public GLB (format=stl exports a watertight mesh for printing); the same browser-only checks run with zero network cost in Rig Doctor, and the full grade with a one-click upgrade in the GLB viewer, through a shared <engine-qa> panel component. The underlying LOD builder (packages/glb-tools's buildLodChain, real meshoptimizer decimation tagged with MSFT_lod) is now also available on generation: send { "lods": true } to POST /api/forge and the finished creation gets a combined LOD-chain variant alongside its delivered mesh, the same opt-in, fire-and-forget pattern as the existing web-delivery variant. (`/docs/engine-qa`) `[feature]`- **Real VRM avatars: spring bones, expressions, and .vrma clips via @pixiv/three-vrm**: The hand-rolled VRM loader is gone. vrm-boot.js now registers the real VRMLoaderPlugin (@pixiv/three-vrm) on the three.ws GLTFLoader, so VRM 0.x and 1.0 avatars get genuine MToon materials, spring-bone physics, node constraints, look-at, and all 18 expression presets, driven live by vrm.update(delta) in AnimationManager and mapped onto the ARKit-52 face-capture driver. VRMAnimationLoaderPlugin loads .vrma clips into the same retargeting pipeline that drives non-VRM humanoids, so a single clip plays on either. The Ready Player Me import page (/import-rpm) now accepts .vrm files alongside .glb, and a long-standing bug that 400'd every import at the final save step (it sent an invalid source value) is fixed. docs/avatar-engines.md upgrades three-vrm from interop to live. (`/docs/avatar-engines`) `[feature, fix]`+- **Restyle and part edits now prove they kept the rig, not just claim it**: Material Studio's AI restyle and seeded colorway variants, plus Restyle Studio's HoloPart "Regenerate part" tool, are now checked against their own source bytes with @three-ws/glb-diff before anything is persisted: a restyle declares it keeps topology, UVs, skeleton, skin, and clips, a part regenerate declares the narrower skeleton-and-clips promise since the part's own shape is meant to change, and the operation throws instead of returning a URL if the real diff shows otherwise. A successful restyle response now carries preserve: { kinds, verified: true } as evidence. Model Diff's underlying engine (packages/glb-diff) grew three independent mesh sub-hashes, topology, uv, and skinWeights, so a caller can tell which kind of change happened instead of one opaque geometry hash, and every lineage step in Restyle Studio that has a parent now shows a "Diff" link that opens Model Diff pre-loaded with that exact before/after pair. Regenerating a part also now mints its own durable lineage version automatically, closing a gap where part edits were not recorded. (`/restyle`) `[feature, improvement]`- **Text-to-motion gets a second GPU backend: MoMask, selectable per request**: The self-hosted text-to-motion worker behind the Animation Studio and POST /api/forge-motion now runs two independent generation backends on the same GPU lane: MDM (Motion Diffusion Model, MIT), the existing default, and MoMask (EricGuo5513/momask-codes, MIT), a residual-VQ tokenizer plus masked and residual transformer that publishes a lower HumanML3D FID (0.045 vs. T2M-GPT's 0.141). Pass model: "momask" to /infer or /api/forge-motion to route a prompt through it instead; omit it and MDM keeps answering as before. Both backends converge on the same (T,22,3) HumanML3D position format and the same shared decode math, so a MoMask clip previews, retargets, and exports exactly like an MDM one. The two projects ship conflicting top-level `utils` packages; the worker resolves that at load time so either backend can be warmed in the same container without the other's modules leaking in. MoMask's checkpoints are staged to production storage and the worker is wired to load them; the first on-GPU deploy and a real in-house benchmark against MDM are tracked as the next step. (`/pose`) `[feature, infra]`- **Three new engine bridges: Unity, Godot, and Unreal, one prompt to a mesh in your editor**: A shared contract (specs/ENGINE_BRIDGE.md) and three real, independent implementations: a Unity UPM package that imports with glTFast, a Godot addon that imports with Godot's own native GLTFDocument, and an Unreal plugin that imports through Unreal's Interchange glTF pipeline. Each one calls only the public Forge API (POST /api/forge to submit, GET /api/forge?job=<id> to poll, a plain HTTPS GET to download), the same free-first routing and anonymous x-forge-client auth every other Forge caller gets, with the same four import settings (generate_colliders, import_materials, scale, destination) mapped onto each engine's own equivalent. A dropdown and a Generate button in each editor: type a prompt, get a mesh dropped into your scene. (`/docs/engine-bridges`) `[feature, sdk]`diff --git a/STRUCTURE.md b/STRUCTURE.mdindex ba7e7cd57..093a62631 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -44,7 +44,7 @@ bottom.| Asset catalog (one search over every ready-made asset) | join + ranking [api/_lib/asset-catalog.js](api/_lib/asset-catalog.js), code generation [api/_lib/asset-snippets.js](api/_lib/asset-snippets.js), REST [api/catalog.js](api/catalog.js) `→ /api/catalog`, MCP tools [api/_mcp/tools/library.js](api/_mcp/tools/library.js), CLI [packages/assets-cli/](packages/assets-cli) | Published as `@three-ws/assets` | The CC0 prop library, the ready-made character library and the motion-clip library joined into one ranked catalog (thousands of items; the live count is `total` on `GET /api/catalog`) that also hands back paste-ready source: the `<model-viewer>` tag the browse grids render with, `<agent-3d>` pinned to the exact published version plus its SRI hash, plain three.js, or React. Reachable three ways off one implementation: `GET /api/catalog`, the free MCP tools `search_catalog` / `get_catalog_item` / `get_item_source` (on `/api/mcp`'s public allowlist, so a plain JSON-RPC call needs no OAuth and no x402, though an MCP client connecting there is sent through sign-in on `initialize`; the keyless `/api/mcp-studio` serves the same three to a client with no account via [api/_mcp-studio/catalog-tools.js](api/_mcp-studio/catalog-tools.js)), and `npx @three-ws/assets add <id>`, which downloads the asset into the caller's project and rewrites the snippet to the local path. Every word of a query must match, with a labelled partial-match fallback so a phrase never dead-ends. Docs: [docs/mcp.md](docs/mcp.md) `→ /docs/mcp`, [docs/api-reference.md](docs/api-reference.md). Tests: [tests/api/mcp-asset-catalog.test.js](tests/api/mcp-asset-catalog.test.js), [tests/api/catalog-endpoint.test.js](tests/api/catalog-endpoint.test.js), [packages/assets-cli/test/](packages/assets-cli/test) || MCP resources and guided prompts | registry and readers [api/_mcp/resources.js](api/_mcp/resources.js), prompts [api/_mcp/prompts.js](api/_mcp/prompts.js), `read_resource` tools [api/_mcp/tools/resources.js](api/_mcp/tools/resources.js) and [api/_mcp3d/tools/resources.js](api/_mcp3d/tools/resources.js), `create_agent` in [api/_mcp/tools/agents.js](api/_mcp/tools/agents.js) over the shared creation path [api/_lib/agent-create.js](api/_lib/agent-create.js), subscriptions table [api/_lib/migrations/20260922120000_mcp_resource_subscriptions.sql](api/_lib/migrations/20260922120000_mcp_resource_subscriptions.sql), manifest generator [scripts/build-mcp-surfaces.mjs](scripts/build-mcp-surfaces.mjs) | Live on `/api/mcp`, `/api/mcp-agent`, `/api/mcp-3d`, `/api/mcp-bazaar` | Live read-only `three://` views of the caller's account (agents, each agent's Solana wallet with balances, limits and freeze state, usage, chat, runs, orders, DCA, intents, wallets, launches) plus the public marketplace, model catalog, x402 catalog and 3D assets, each as JSON or markdown and each also reachable through the `read_resource` tool. `resources/subscribe` stores a fingerprint per client and the authenticated GET event stream emits `notifications/resources/updated` when it moves; a wallet moves when its latest signature changes. Seventeen guided prompts render against each server's live tools/list, so a server only offers flows whose tools it publishes, and venue flows switch to their executing tools once those ship. `npm run audit:mcp-surfaces` keeps `server*.json` and `/.well-known/mcp.json` in step with the code. Docs: [docs/mcp.md](docs/mcp.md) `→ /docs/mcp`. Tests: [tests/mcp-resources.test.js](tests/mcp-resources.test.js), [tests/mcp-prompts.test.js](tests/mcp-prompts.test.js) || Terminal avatar (any avatar or agent body, live in a terminal) | [packages/tty-avatar/](packages/tty-avatar) | Published as `@three-ws/tty-avatar` | `npx @three-ws/tty-avatar <avatar id>` draws the avatar in colour at 24 fps in any terminal: a software rasterizer ([packages/tty-avatar/src/raster.js](packages/tty-avatar/src/raster.js), z-buffered scanline fill, key + fill + rim lighting) over a subpixel grid that three encoders turn into truecolor half-blocks, braille, or plain ASCII ([packages/tty-avatar/src/encode.js](packages/tty-avatar/src/encode.js)). Sources: a `.glb` path, a URL, an avatar id (`/api/avatars/:id`), `agent:<id>` (the agent's bound body via `/api/agents/:id`), or a three.ws page URL. Moods are procedural whole-body motion ([packages/tty-avatar/src/moods.js](packages/tty-avatar/src/moods.js)), so a rigless prop animates too, and they cross-fade. The point of it: `install-hooks --write` merges nine Claude Code hooks whose command is a bare `cat > ~/.three-ws/tty-avatar/event.json` (zero startup cost per tool call), the viewer polls that file and maps each payload to a mood and a caption ([packages/tty-avatar/src/state.js](packages/tty-avatar/src/state.js)), so the avatar thinks, works, errors, asks and celebrates in step with the agent. Every avatar and agent page's Embed tab prints the command ([src/avatar-page.js](src/avatar-page.js)). Docs: [docs/tty-avatar.md](docs/tty-avatar.md) `→ /docs/tty-avatar`. Tests: [packages/tty-avatar/test/](packages/tty-avatar/test) (builds a real GLB in memory and exercises loader, rasterizer, encoders, moods, state bridge, hook installer and CLI) |-| Model Diff (what changed between two GLBs) | [pages/diff.html](pages/diff.html) `→ /diff` + page runtime [src/model-diff.js](src/model-diff.js), 3D stage [src/model-diff-stage.js](src/model-diff-stage.js), styles [public/model-diff.css](public/model-diff.css), engine [packages/glb-diff/](packages/glb-diff), free API [api/3d/diff.js](api/3d/diff.js) `→ /api/3d/diff` (catalog entry [api/_lib/3d-catalog/diff.js](api/_lib/3d-catalog/diff.js)), MCP tool `diff_models` in [api/_mcp/tools/models.js](api/_mcp/tools/models.js) | Live | The check that catches the most expensive silent failure in an asset pipeline: a checksum flags every re-export, and cannot tell a lossless recompression from a rig that quietly lost three finger joints. Objects are paired in three passes the way git pairs renamed files (name, then content hash, then similarity), so an exporter that renumbers `Mesh.001` reads as a rename rather than a rewrite, and a node that kept its name but changed parent reads as a move. Vertex data is hashed at a 1e-4 quantum with normals, UVs and **skin weights** included, so a Draco round trip registers as nothing and a re-skin registers as a change. Every difference carries a severity (`none` to `breaking`), where breaking means something a consumer addresses by name is gone: a clip, a joint, a mesh. One engine, four surfaces, so a CI verdict can never disagree with the page: the browser page (drop two files, nothing uploaded; overlay / wipe / side-by-side in 3D, clicking a row frames that node), the free keyless API (`?a=&b=`, `format=markdown` for a pull-request comment), the `glb-diff` CLI (`--fail-on breaking`, exit 2 reserved for "could not run"), and the MCP tool. Docs: [docs/model-diff.md](docs/model-diff.md) `→ /docs/model-diff`. Tests: [packages/glb-diff/tests/glb-diff.test.js](packages/glb-diff/tests/glb-diff.test.js), [tests/model-diff-api.test.js](tests/model-diff-api.test.js) |+| Model Diff (what changed between two GLBs) | [pages/diff.html](pages/diff.html) `→ /diff` + page runtime [src/model-diff.js](src/model-diff.js), 3D stage [src/model-diff-stage.js](src/model-diff-stage.js), styles [public/model-diff.css](public/model-diff.css), engine [packages/glb-diff/](packages/glb-diff), free API [api/3d/diff.js](api/3d/diff.js) `→ /api/3d/diff` (catalog entry [api/_lib/3d-catalog/diff.js](api/_lib/3d-catalog/diff.js)), MCP tool `diff_models` in [api/_mcp/tools/models.js](api/_mcp/tools/models.js) | Live | The check that catches the most expensive silent failure in an asset pipeline: a checksum flags every re-export, and cannot tell a lossless recompression from a rig that quietly lost three finger joints. Objects are paired in three passes the way git pairs renamed files (name, then content hash, then similarity), so an exporter that renumbers `Mesh.001` reads as a rename rather than a rewrite, and a node that kept its name but changed parent reads as a move. Vertex data is hashed at a 1e-4 quantum with normals, UVs and **skin weights** included, so a Draco round trip registers as nothing and a re-skin registers as a change. Positions, UVs and skin weights also hash independently (`topology`/`uv`/`skinWeights` on every mesh field), so a caller can tell exactly which kind of edit happened; [api/_lib/preserve-contract.js](api/_lib/preserve-contract.js) builds directly on those fields plus the skins/animations sections so an edit can declare what it promises to keep (topology, UVs, skeleton, skin, clips) and refuse to report success if that promise breaks, the check behind [Restyle Studio](docs/restyle.md)'s material restyles, seeded variants, and HoloPart part regenerations. Every difference carries a severity (`none` to `breaking`), where breaking means something a consumer addresses by name is gone: a clip, a joint, a mesh. One engine, four surfaces, so a CI verdict can never disagree with the page: the browser page (drop two files, nothing uploaded; overlay / wipe / side-by-side in 3D, clicking a row frames that node), the free keyless API (`?a=&b=`, `format=markdown` for a pull-request comment), the `glb-diff` CLI (`--fail-on breaking`, exit 2 reserved for "could not run"), and the MCP tool. Docs: [docs/model-diff.md](docs/model-diff.md) `→ /docs/model-diff`. Tests: [packages/glb-diff/tests/glb-diff.test.js](packages/glb-diff/tests/glb-diff.test.js), [tests/model-diff-api.test.js](tests/model-diff-api.test.js), [tests/api/preserve-contract.test.js](tests/api/preserve-contract.test.js) || Rig Doctor (will this GLB animate?) | [pages/rig-doctor.html](pages/rig-doctor.html) `→ /rig-doctor`, analysis [src/rig-report.js](src/rig-report.js), page runtime [src/rig-doctor-page.js](src/rig-doctor-page.js), styles [public/rig-doctor.css](public/rig-doctor.css) | Live | The answer to the most expensive silent failure on the platform: a rig loads, renders, and never moves, because clips address bones by name and this skeleton calls them something else. Drop a `.glb` and the page reads its glTF JSON chunk in the browser, names the authoring convention (twelve fingerprints, from Mixamo and Ready Player Me to Unreal, VRM, MMD, Biped, Rigify, and HumanIK), and scores four limb groups independently against the 52-joint canonical set, because "62% covered" is not actionable and "your legs will not move" is. The verdict mirrors the runtime gate in [src/animation-manager.js](src/animation-manager.js) exactly (a skinned mesh plus 8 mapped joints), so it predicts rather than approximates. It then does two things a report cannot: mounts the real [src/avatar-pose.js](src/avatar-pose.js) stage on a blob URL of the file so the user watches their own rig perform the actual clip library, and runs [src/glb-canonicalize.js](src/glb-canonicalize.js) in-browser to hand back a repaired GLB with canonical joint names. Nothing is uploaded: the only network calls are for the clip library and the sample rigs. Also emits a schema-v1 manifest, an `<agent-3d>` snippet, and the matching [packages/avatar-cli/](packages/avatar-cli) commands. Docs: [docs/rig-doctor.md](docs/rig-doctor.md) `→ /docs/rig-doctor`. Tests: [tests/rig-report.test.js](tests/rig-report.test.js) || The pump.fun pill (`/pill`) | [pages/pill.html](pages/pill.html) `→ /pill` + [src/pill.js](src/pill.js) + [src/pill.css](src/pill.css), rigger [scripts/rig-pill-mascot.py](scripts/rig-pill-mascot.py), decimator [scripts/decimate-glb.mjs](scripts/decimate-glb.mjs), assets [public/avatars/pumpfun-pill-cupsey.glb](public/avatars/pumpfun-pill-cupsey.glb) (rigged) + `pumpfun-pill-cupsey-static.glb` (the rigger's input) | Live | pump.fun verified $THREE as officially ours, and this is the thank-you: their pill mascot rigged, animated, and drivable in the browser. WASD or a touch joystick walks it, Shift runs, Space jumps, drag orbits, and the toolbar fires wave/jump/dance. The stage plays the model's own six embedded clips, so it needs no retargeting at load and no clip fetch. The model could not go through [workers/rig](workers/rig): a capsule with four stubby nubs has no neck, no separate head and no long limbs for a humanoid predictor to find, so it got its own pipeline. That pipeline is general to capsule-with-nubs mascots, not to this character: limbs discovered from the mesh's distance transform, medial curves traced with a minimum-cost path, skin weights decided by walking each vertex inward to the medial axis of the part it is skin for (straight-line and geodesic distance both weld the raised hand to the cheek it rests against), and the neutral standing pose baked into the shipped geometry so bind and rest coincide. Canonical bone names mean the whole clip library retargets onto it at 100% coverage. Docs: [docs/pill-mascot.md](docs/pill-mascot.md) `→ /docs/pill-mascot`. Tests: [tests/pill-rig.test.js](tests/pill-rig.test.js) || Talking page guide | [page-agent-sdk/](page-agent-sdk) | Published as `@three-ws/page-agent` | Drop-in rigged 3D agent that narrates any page + visitor avatar picker. `<page-agent>` web component. Rigged-only catalog. `preset="…"` resolves one of 5 personas (greeting/role/suggested-prompt chips/tool allowlist) — see [page-agent-sdk/README.md#persona-presets](page-agent-sdk/README.md#persona-presets). See [page-agent-sdk/PUBLISHING.md](page-agent-sdk/PUBLISHING.md) |@@ -139,7 +139,7 @@ bottom.| `pay` registry listing (Solana Foundation pay-skills) | Projection [api/_lib/service-catalog/pay-skills.js](api/_lib/service-catalog/pay-skills.js), generator [scripts/build-pay-skills.mjs](scripts/build-pay-skills.mjs) (`npm run build:pay-skills` / `check:pay-skills` / `verify:pay-skills`), output [distributions/pay-skills/](distributions/pay-skills/README.md), guard [tests/pay-skills.test.js](tests/pay-skills.test.js), runbook § 8 of [docs/ops/x402-discovery-listings.md](docs/ops/x402-discovery-listings.md) | Ready to submit | Three providers (`three-ws/3d`, `three-ws/market-data`, `three-ws/agent-trust`) for the registry behind the Solana Foundation `pay` CLI and MCP server, in the upstream layout so publishing is a copy. Paths, schemas, examples and prices come from the service catalog and the live price functions; registry-grade copy (verb-first 24-64 char ASCII summaries, every parameter described) lives in the projection and is rule-checked at build. `verify:pay-skills` runs the registry's own `pay catalog check` with live, never-paying probes; all three pass the Solana gate. The upstream PR is owner-gated. || Conversational refinement + remix economy | Iterate: [api/_mcp-studio/tools.js](api/_mcp-studio/tools.js) `refine_model` (free, on `/api/mcp-studio`) + [mcp-server/src/tools/refine-model.js](mcp-server/src/tools/refine-model.js) (paid stdio, $0.25); shared lineage core [mcp-server/src/tools/_lineage.js](mcp-server/src/tools/_lineage.js). Remix (paid track): feed [api/remix-feed.js](api/remix-feed.js) `→ /api/remix-feed` (free browse/publish/lineage), settlement [api/x402/remix-asset.js](api/x402/remix-asset.js) `→ /api/x402/remix-asset` + core [api/_lib/remix-settlement.js](api/_lib/remix-settlement.js) + split math [api/_lib/remix-royalty.js](api/_lib/remix-royalty.js). Docs [docs/remix.md](docs/remix.md), [docs/mcp-studio.md](docs/mcp-studio.md). | Live | Talk to a model to iterate it ("make it metallic") — real anchored re-generation with a revertable/branchable version lineage rendered as a viewer version strip; free on both the OpenAI 3D Studio and the paid MCP server. Creators publish a finished model as remixable (provenance + license + royalty on the existing `forge_creations` rows — no parallel store); another agent pays $0.25 USDC to remix it and a creator-set royalty (≤20%, capped) routes on-chain to the original creator via the audited `transferSolanaUSDC` rail. Split/caps/payout unit-tested ([tests/remix-settlement.test.js](tests/remix-settlement.test.js), [tests/remix-royalty.test.js](tests/remix-royalty.test.js), [tests/refine-lineage.test.js](tests/refine-lineage.test.js)). Free track stays crypto-free. Prompt 09. || Terminal renderer (3D in a shell, no GPU) | Renderer core [packages/tty-3d/](packages/tty-3d) (`@three-ws/tty-3d`, CLI `three-tty`), hosted stream [api/tty.js](api/tty.js) `→ /tty`, `/tty/:id`, `/api/tty`, page [pages/tty.html](pages/tty.html) + [src/tty-page.js](src/tty-page.js) `→ /tty`. Docs: [docs/tty.md](docs/tty.md). Tests: [packages/tty-3d/tests/tty-3d.test.js](packages/tty-3d/tests/tty-3d.test.js), [tests/api-tty.test.js](tests/api-tty.test.js) | Live | `curl three.ws/tty` and a rigged agent walks in your terminal, with nothing installed on either side. A pure-CPU software rasterizer (z-buffer, per-vertex linear blend skinning off the glTF animation samplers, meshopt decode on the way in) draws into a framebuffer the size of the caller's terminal and encodes it as `▀` half-blocks, so one cell carries two independently coloured pixels and pixels come out square. The server streams paced frames as `text/plain`, so the HTTP response IS the animation. Sibling of [packages/tty-avatar/](packages/tty-avatar), which adds moods, avatar-id resolution and Claude Code hooks on top of a terminal renderer but deliberately does not do skeletal animation; this package owns the 3D. |-| Restyle Studio (material/PBR editor + AI restyle + variants) | [pages/restyle.html](pages/restyle.html) `→ /restyle`, [src/restyle.js](src/restyle.js). PBR preset/variant library [packages/viewer-presets/src/materials.js](packages/viewer-presets/src/materials.js) (`@three-ws/viewer-presets`). AI restyle + persistence core [api/_lib/material-studio-store.js](api/_lib/material-studio-store.js), free hosted endpoint [api/material-studio.js](api/material-studio.js) `→ /api/material-studio`; paid agent twin [mcp-server/src/tools/restyle-material.js](mcp-server/src/tools/restyle-material.js) (`restyle_material`, $0.05 stdio MCP), thin core [mcp-server/src/tools/_material-core.js](mcp-server/src/tools/_material-core.js). Shares the `refine_model` lineage core ([mcp-server/src/tools/_lineage.js](mcp-server/src/tools/_lineage.js)) so a restyle/variant is just another kind of version, feeding prompt 09 remix. Docs: [docs/restyle.md](docs/restyle.md), [docs/mcp-tools.md](docs/mcp-tools.md). | Live | Re-skin any GLB without regenerating its mesh: live PBR editing (color/metalness/roughness/emissive/texture) with a one-click preset library (18 looks: chrome, gold, copper, brushed steel, gunmetal, matte, glossy, rubber, ceramic, glass, real glass, wood, stone, fabric, skin, car paint, neon, holographic), seeded reproducible colorway variants (mulberry32 PRNG, so the same base plus seed yields the same set), and free-text AI restyle ("make it chrome", "cyberpunk neon") via IBM Granite-proposed PBR factors applied + re-exported server-side. Every AI restyle / saved checkpoint mints a real, `gltf-validator`-checked, durably-stored GLB recorded in an immutable parent to child lineage: non-destructive in the durable sense, not just an in-browser Reset. Every server failure surfaces the API's own `error_description`, and a storage outage says so and points at Export GLB, which is wholly in-browser. Roadmap prompt 06. |+| Restyle Studio (material/PBR editor + AI restyle + variants) | [pages/restyle.html](pages/restyle.html) `→ /restyle`, [src/restyle.js](src/restyle.js). PBR preset/variant library [packages/viewer-presets/src/materials.js](packages/viewer-presets/src/materials.js) (`@three-ws/viewer-presets`). AI restyle + persistence core [api/_lib/material-studio-store.js](api/_lib/material-studio-store.js), free hosted endpoint [api/material-studio.js](api/material-studio.js) `→ /api/material-studio`; paid agent twin [mcp-server/src/tools/restyle-material.js](mcp-server/src/tools/restyle-material.js) (`restyle_material`, $0.05 stdio MCP), thin core [mcp-server/src/tools/_material-core.js](mcp-server/src/tools/_material-core.js). Shares the `refine_model` lineage core ([mcp-server/src/tools/_lineage.js](mcp-server/src/tools/_lineage.js)) so a restyle/variant is just another kind of version, feeding prompt 09 remix. Docs: [docs/restyle.md](docs/restyle.md), [docs/mcp-tools.md](docs/mcp-tools.md). | Live | Re-skin any GLB without regenerating its mesh: live PBR editing (color/metalness/roughness/emissive/texture) with a one-click preset library (18 looks: chrome, gold, copper, brushed steel, gunmetal, matte, glossy, rubber, ceramic, glass, real glass, wood, stone, fabric, skin, car paint, neon, holographic), seeded reproducible colorway variants (mulberry32 PRNG, so the same base plus seed yields the same set), and free-text AI restyle ("make it chrome", "cyberpunk neon") via IBM Granite-proposed PBR factors applied + re-exported server-side. Every AI restyle / saved checkpoint mints a real, `gltf-validator`-checked, durably-stored GLB recorded in an immutable parent to child lineage: non-destructive in the durable sense, not just an in-browser Reset. Every restyle, variant, and HoloPart part regeneration is checked against its own source with [Model Diff](docs/model-diff.md)'s engine via [api/_lib/preserve-contract.js](api/_lib/preserve-contract.js) before it is ever persisted: topology, UVs, skeleton, skin and clips must come back unchanged (a part regenerate relaxes that to skeleton and clips, since the selected part's own shape is meant to change), or the operation throws instead of returning a URL. Each lineage step with a parent exposes a "Diff" link straight to the Model Diff page, pre-loaded with that exact before/after pair. Every server failure surfaces the API's own `error_description`, and a storage outage says so and points at Export GLB, which is wholly in-browser. Roadmap prompt 06. || Embodiment: a living agent body in the chat | Hosted embed [pages/embodiment/embed.html](pages/embodiment/embed.html) `→ /embodiment/embed` (Vite input + vercel route, `frame-ancestors *`); engine [apps-sdk/embodiment/embodiment-stage.js](apps-sdk/embodiment/embodiment-stage.js) (`EmbodimentStage`) + [overlay.js](apps-sdk/embodiment/overlay.js); persona tools (free) [api/_mcp-studio/persona-tools.js](api/_mcp-studio/persona-tools.js) → `/api/mcp-studio` (`create_agent_persona`, `get_agent_persona`, `persona_say`; deliberately absent from the ChatGPT plugin surface `/api/mcp-chatgpt`, because their widget needs `frameDomains`) and (paid) [api/_mcp3d/tools/studio.js](api/_mcp3d/tools/studio.js); shared inline-body artifact [api/_lib/embodiment-artifact.js](api/_lib/embodiment-artifact.js); identity store [api/_lib/persona-store.js](api/_lib/persona-store.js) (Postgres `agent_personas` + fs fallback + durable R2 GLB); reload route [api/mcp3d/persona.js](api/mcp3d/persona.js) `→ /api/mcp3d/persona`; live chain-state feed [api/mcp3d/persona-identity.js](api/mcp3d/persona-identity.js) `→ /api/mcp3d/persona-identity` (polled only when the embed is opened with `?wallet=1`). Emotion/rig/lip-sync cores under [src/embodiment/](src/embodiment) + [src/voice/](src/voice). | Live | A generated avatar becomes a persistent, named body that renders inline in ChatGPT/Claude: it lip-syncs each reply, blends the matching expression + gesture, idles between turns, and reloads by `persona_id` in a fresh session (the id is the capability, no sign-in). Rides the universal canonicalize/retarget clip library; a rig without face morphs animates the jaw, a non-humanoid GLB falls back to a gentle idle (`decideRigMode`/`supportsCanonicalClips`), never a bind-pose T-pose. Zero crypto/token surface. Tests: [tests/persona-store.test.js](tests/persona-store.test.js), [tests/api/persona-resolve-route.test.js](tests/api/persona-resolve-route.test.js), [tests/api/persona-identity-route.test.js](tests/api/persona-identity-route.test.js), [tests/mcp-studio.test.js](tests/mcp-studio.test.js), [tests/embodiment-rig-mode.test.js](tests/embodiment-rig-mode.test.js). Evidence: [prompts/store-submissions/_generated/embodiment/](prompts/store-submissions/_generated/embodiment/). Store-submission prompt 07. || Claude.ai artifact embed + builder | Endpoint [api/artifact.js](api/artifact.js) `→ /api/artifact`, prebuilt viewer [public/artifact-viewer.bundle.js](public/artifact-viewer.bundle.js) (source [scripts/artifact-viewer/src.js](scripts/artifact-viewer/src.js), `npm run build:artifact-viewer`), builder page [public/artifact/index.html](public/artifact/index.html) `→ /artifact` + [README](public/artifact/README.md), contract [specs/CLAUDE_ARTIFACT.md](specs/CLAUDE_ARTIFACT.md), vendored sandbox CSP [public/claude-artifact-csp.txt](public/claude-artifact-csp.txt) (refresh: [scripts/refresh-claude-csp.mjs](scripts/refresh-claude-csp.mjs)). | Live | `GET /api/artifact?agent=<uuid>` returns ONE self-contained HTML document with three.js, GLTFLoader, the viewer and the agent GLB all inlined, because Claude's artifact sandbox CSP blocks every external script and fetch. Paste the URL into a Claude conversation and the agent renders inline. The builder page is the pre-flight: it lists real public agents that carry an embeddable avatar (`/api/agents/public?avatar=1`), renders the response in a sandboxed iframe under the same CSP Claude applies, and reports payload size, fetch time, frame render time and sandbox compliance before you paste. Size is graded against the ceiling the endpoint can actually emit (a 6 MB model base64-inlines to 8 MB, plus the 565 KB viewer), not against the raw model cap, so a large-but-accepted artifact is not flagged as over budget. `?model=<glb url>` is the viewer-only lane (allowlisted https origins, SSRF-guarded, 6 MB cap). Tests: [tests/api/artifact.test.js](tests/api/artifact.test.js) pins the generated HTML against the vendored Claude CSP. || Avatar Artifact: the standalone shareable viewer | Page [pages/avatar-artifact.html](pages/avatar-artifact.html) `→ /avatar-artifact`, scene + artifact loader [src/avatar-artifact.js](src/avatar-artifact.js), docs [docs/avatar-artifact.md](docs/avatar-artifact.md). | Live | One page, one avatar, no wrapper: the URL you paste into an `<iframe>` on someone else's site or send to a person who has never heard of three.ws. `?agent=<uuid>` renders that agent's avatar from the live public record (the name becomes the heading and the document title, an Open profile link appears), `?model=<glb url>` renders any GLB from the same allowlisted hosts `/api/artifact` enforces, and a bare link renders the house portrait: a procedural figure that tracks cursor, touch and arrow keys. Ships no third-party CDN (three.js is bundled, because an embed host never agreed to a cross-origin script) and suspends its render loop on a hidden tab. An avatar with no baked clips is driven by the shared retargeted `idle` from the universal clip library rather than left in a bind-pose T-pose. Every failure lane (no such agent, private avatar, no avatar yet, blocked host, dead model, no WebGL) has its own sentence and its own next move; the Copy embed snippet carries the artifact parameters so the iframe shows what you were looking at. |diff --git a/data/changelog.json b/data/changelog.jsonindex bab24c90d..fe91e2f77 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,16 @@{"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.","entries": [+ {+ "date": "2026-10-12",+ "title": "Restyle and part edits now prove they kept the rig, not just claim it",+ "link": "/restyle",+ "summary": "Material Studio's AI restyle and seeded colorway variants, plus Restyle Studio's HoloPart \"Regenerate part\" tool, are now checked against their own source bytes with @three-ws/glb-diff before anything is persisted: a restyle declares it keeps topology, UVs, skeleton, skin, and clips, a part regenerate declares the narrower skeleton-and-clips promise since the part's own shape is meant to change, and the operation throws instead of returning a URL if the real diff shows otherwise. A successful restyle response now carries preserve: { kinds, verified: true } as evidence. Model Diff's underlying engine (packages/glb-diff) grew three independent mesh sub-hashes, topology, uv, and skinWeights, so a caller can tell which kind of change happened instead of one opaque geometry hash, and every lineage step in Restyle Studio that has a parent now shows a \"Diff\" link that opens Model Diff pre-loaded with that exact before/after pair. Regenerating a part also now mints its own durable lineage version automatically, closing a gap where part edits were not recorded.",+ "tags": [+ "feature",+ "improvement"+ ]+ },{"date": "2026-10-12","title": "Text-to-motion gets a second GPU backend: MoMask, selectable per request",diff --git a/docs/forge.md b/docs/forge.mdindex 95f631cdb..846ca4ad8 100644--- a/docs/forge.md+++ b/docs/forge.md@@ -278,6 +278,17 @@ curl -s 'https://three.ws/api/forge-holopart?job=<job_id>'`/api/forge-segment` and the `partcrafter` backend both produce); FBX isrejected the same way stylize and segment reject it.+**Regenerate part keeps the rig.** Before the regenerated part is swapped+into the live model, Restyle Studio diffs the whole-model bytes HoloPart+received against the whole-model bytes it returned with+`@three-ws/glb-diff` (`api/_lib/preserve-contract.js`, declaring+`['skeleton', 'clips']`), and refuses the swap if the armature or any+animation clip changed. A successful regenerate is also minted as a new+durable version in the real lineage automatically (no separate "Save+version" click needed), and the lineage strip's "Diff" link opens+[Model Diff](./model-diff.md) pre-loaded with exactly that before/after+pair.+## Mesh tools: repair, smooth, decimateThe **Optimize** panel under a finished model, and the **Edit mesh** sectiondiff --git a/docs/model-diff.md b/docs/model-diff.mdindex aa586c675..13abf5ee9 100644--- a/docs/model-diff.md+++ b/docs/model-diff.md@@ -112,6 +112,8 @@ The report distinguishes two kinds of geometry edit, because they mean different- *same vertex and triangle count, different vertex data*: usually a re-bake, a re-skin, or a transform applied in place- *vertex data rewritten*: a decimation, a remesh, or a different asset entirely+Underneath the combined geometry hash, three fields move independently so a caller can tell exactly which kind of edit happened: `topology` (vertex positions or the index buffer), `uv` (`TEXCOORD_0`/`TEXCOORD_1`), and `skinWeights` (`JOINTS_0`/`WEIGHTS_0`, the per-vertex skin binding, as distinct from the skeleton resource below). A material restyle that only calls glTF Material setters should never move any of the three; an edit that promises it won't can check that promise with `api/_lib/preserve-contract.js`, which runs this same diff and refuses to report success if a declared field changed. [Restyle Studio](./restyle.md) and its part-edit tools (regenerate/swap via HoloPart) are the first two callers.+### SkeletonsJoint lists are compared by name. A removed joint is `breaking` and the report names it. A changed inverse-bind matrix set is `major` and says why: the bind pose moved, so existing clips will deform differently even though every joint is still present.diff --git a/docs/restyle.md b/docs/restyle.mdindex 177d5e6e4..2a5686a61 100644--- a/docs/restyle.md+++ b/docs/restyle.md@@ -70,7 +70,8 @@ A restyle response carries the applied factors plus the version lineage:},"materialsEdited": 4,"lineage": [ { "index": 0, "glbUrl": "…" }, { "index": 1, "glbUrl": "…" } ],- "activeIndex": 1+ "activeIndex": 1,+ "preserve": { "kinds": ["topology", "uv", "skeleton", "skin", "clips"], "verified": true }}```@@ -83,7 +84,7 @@ Pass the returned `lineage` array back as `parent_lineage` on the next call to e- **Texture generation is best-effort.** Past the free daily quota the image lane returns a payment-required signal; the studio surfaces that as a note and keeps the flat PBR restyle it already applied. It never fakes a texture.- **Bounded, not gated.** The web endpoint is free but rate-limited per IP (separate limits for uploads and restyle/variants). Instructions are capped at 300 characters and uploads at 64 MB.- **Reset vs. revert.** Reset restores the original material values in the current tab. Reverting to an earlier durable GLB is a separate action: click its entry in the Versions strip. Reverting also re-anchors the source: the next AI restyle, Save version, or "Save all as versions" reads that version's bytes and branches from it, rather than from the newest checkpoint.-- **No mesh changes.** Geometry, UVs, and rigging are never modified, so a restyle can never break animation or distort a shape.+- **No mesh changes, verified, not just promised.** Every restyle and variant is checked server-side with `@three-ws/glb-diff` against its own source before it is ever persisted (`api/_lib/preserve-contract.js`): topology, UVs, skeleton, skin, and clips must all come back unchanged, or the operation throws instead of handing back a URL. The response carries `preserve: { kinds, verified: true }` as proof. A "Regenerate part" edit runs the same check, scoped to `skeleton` and `clips` (the part itself legitimately changes shape); each lineage step with a parent exposes a "Diff" link that opens [Model Diff](./model-diff.md) pre-loaded with that exact before/after pair.## Relateddiff --git a/packages/glb-diff/README.md b/packages/glb-diff/README.mdindex 85a4683d1..c470a804f 100644--- a/packages/glb-diff/README.md+++ b/packages/glb-diff/README.md@@ -88,6 +88,23 @@ build; a deleted bone that every animation clip targets should.`DESCRIPTION_VERSION` and `CHANGESET_VERSION` are exported so a cache or a storedreport can tell whether it was produced by a compatible version.+## Mesh fields++A mesh diff's `changes` array can report these fields on top of the combined+`geometry` hash, each independent of the others so an edit can be checked+against exactly the kind of change it is not supposed to make:++| Field | What moved |+| --- | --- |+| `topology` | Vertex positions (`POSITION`) or the index buffer. Connectivity changed. |+| `uv` | `TEXCOORD_0`/`TEXCOORD_1`. The mesh's shape is identical; its texture mapping is not. |+| `skinWeights` | `JOINTS_0`/`WEIGHTS_0`. The per-vertex skin binding changed, independent of the skeleton itself. |++`api/_lib/preserve-contract.js` builds on exactly these fields, plus the+`skins` and `animations` sections, to let an edit operation declare which of+topology/UVs/skeleton/skin/clips it keeps and verify that promise against the+real diff instead of trusting its own say-so.+## Related- [`@three-ws/render`](../render): rasterize a GLB to PNG with no GPU, for adiff --git a/public/changelog-recent.json b/public/changelog-recent.jsonindex 79ce95cad..82e98de93 100644--- a/public/changelog-recent.json+++ b/public/changelog-recent.json@@ -1,11 +1,11 @@{- "generated_at": "2026-10-12T08:21:28.589Z",+ "generated_at": "2026-10-12T09:12:05.233Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws","url": "https://three.ws"},- "total": 4042,+ "total": 4043,"complete": false,"full_feed": "/changelog.json","entries": [@@ -81,6 +81,17 @@"fix"]},+ {+ "date": "2026-10-12",+ "type": "update",+ "title": "Restyle and part edits now prove they kept the rig, not just claim it",+ "summary": "Material Studio's AI restyle and seeded colorway variants, plus Restyle Studio's HoloPart \"Regenerate part\" tool, are now checked against their own source bytes with @three-ws/glb-diff before anything is persisted: a restyle declares it keeps topology, UVs, skeleton, skin, and clips, a part regenerate declares the narrower skeleton-and-clips promise since the part's own shape is meant to change, and the operation throws instead of returning a URL if the real diff shows otherwise. A successful restyle response now carries preserve: { kinds, verified: true } as evidence. Model Diff's underlying engine (packages/glb-diff) grew three independent mesh sub-hashes, topology, uv, and skinWeights, so a caller can tell which kind of change happened instead of one opaque geometry hash, and every lineage step in Restyle Studio that has a parent now shows a \"Diff\" link that opens Model Diff pre-loaded with that exact before/after pair. Regenerating a part also now mints its own durable lineage version automatically, closing a gap where part edits were not recorded.",+ "link": "/restyle",+ "tags": [+ "feature",+ "improvement"+ ]+ },{"date": "2026-10-12","type": "update",@@ -1535,16 +1546,6 @@"tags": ["launch"]- },- {- "date": "2026-10-09",- "type": "launch",- "title": "three.ws for Grok Bot: a free 3D studio and a body for Grok",- "summary": "Everything Grok Bot can do with three.ws on one page: generate textured 3D models, rig avatars, find ready-made CC0 assets and run your agents through one custom MCP connector. Real models made minutes ago, the exact connector settings, three recipes to schedule and the Grok skill file. Free, no account, no key.",- "link": "/grok",- "tags": [- "launch"- ]}]}diff --git a/public/changelog.json b/public/changelog.jsonindex e0c9d175d..23f7034e1 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-10-12T08:21:28.566Z",+ "generated_at": "2026-10-12T09:12:05.210Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -78,6 +78,17 @@"fix"]},+ {+ "date": "2026-10-12",+ "type": "update",+ "title": "Restyle and part edits now prove they kept the rig, not just claim it",+ "summary": "Material Studio's AI restyle and seeded colorway variants, plus Restyle Studio's HoloPart \"Regenerate part\" tool, are now checked against their own source bytes with @three-ws/glb-diff before anything is persisted: a restyle declares it keeps topology, UVs, skeleton, skin, and clips, a part regenerate declares the narrower skeleton-and-clips promise since the part's own shape is meant to change, and the operation throws instead of returning a URL if the real diff shows otherwise. A successful restyle response now carries preserve: { kinds, verified: true } as evidence. Model Diff's underlying engine (packages/glb-diff) grew three independent mesh sub-hashes, topology, uv, and skinWeights, so a caller can tell which kind of change happened instead of one opaque geometry hash, and every lineage step in Restyle Studio that has a parent now shows a \"Diff\" link that opens Model Diff pre-loaded with that exact before/after pair. Regenerating a part also now mints its own durable lineage version automatically, closing a gap where part edits were not recorded.",+ "link": "/restyle",+ "tags": [+ "feature",+ "improvement"+ ]+ },{"date": "2026-10-12","type": "update",diff --git a/public/changelog.xml b/public/changelog.xmlindex 8584436fa..bcc079e54 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -62,6 +62,14 @@<category>feature</category><description>The hand-rolled VRM loader is gone. vrm-boot.js now registers the real VRMLoaderPlugin (@pixiv/three-vrm) on the three.ws GLTFLoader, so VRM 0.x and 1.0 avatars get genuine MToon materials, spring-bone physics, node constraints, look-at, and all 18 expression presets, driven live by vrm.update(delta) in AnimationManager and mapped onto the ARKit-52 face-capture driver. VRMAnimationLoaderPlugin loads .vrma clips into the same retargeting pipeline that drives non-VRM humanoids, so a single clip plays on either. The Ready Player Me import page (/import-rpm) now accepts .vrm files alongside .glb, and a long-standing bug that 400'd every import at the final save step (it sent an invalid source value) is fixed. docs/avatar-engines.md upgrades three-vrm from interop to live.</description></item>+ <item>+ <title>Restyle and part edits now prove they kept the rig, not just claim it</title>+ <link>https://three.ws/restyle</link>+ <guid isPermaLink="false">2026-10-12:Restyle and part edits now prove they kept the rig, not just claim it</guid>+ <pubDate>Mon, 12 Oct 2026 12:00:00 GMT</pubDate>+ <category>feature</category>+ <description>Material Studio's AI restyle and seeded colorway variants, plus Restyle Studio's HoloPart "Regenerate part" tool, are now checked against their own source bytes with @three-ws/glb-diff before anything is persisted: a restyle declares it keeps topology, UVs, skeleton, skin, and clips, a part regenerate declares the narrower skeleton-and-clips promise since the part's own shape is meant to change, and the operation throws instead of returning a URL if the real diff shows otherwise. A successful restyle response now carries preserve: { kinds, verified: true } as evidence. Model Diff's underlying engine (packages/glb-diff) grew three independent mesh sub-hashes, topology, uv, and skinWeights, so a caller can tell which kind of change happened instead of one opaque geometry hash, and every lineage step in Restyle Studio that has a parent now shows a "Diff" link that opens Model Diff pre-loaded with that exact before/after pair. Regenerating a part also now mints its own durable lineage version automatically, closing a gap where part edits were not recorded.</description>+ </item><item><title>Text-to-motion gets a second GPU backend: MoMask, selectable per request</title><link>https://three.ws/pose</link>diff --git a/public/features.json b/public/features.jsonindex 8c6137631..605525fd7 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-10-12T08:21:28.552Z",+ "generated_at": "2026-10-12T09:12:05.196Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",