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.

fix(avatar-studio): load the studio's manifest, icons and frames from paths that actually resolve

nirholas4aa1ebbf5670
diff --git a/avatar-sdk/src/creator.js b/avatar-sdk/src/creator.js
index a0abe1f5a..261632884 100644
--- a/avatar-sdk/src/creator.js
+++ b/avatar-sdk/src/creator.js
@@ -12,14 +12,17 @@
// the `saveBlob()` helper instead, which posts to three.ws's /api/avatars
// pipeline using a bearer token.
-const DEFAULT_STUDIO_URL = 'https://three.ws/avatar-studio/';
+// Explicitly the studio's index file: three.ws routes the bare
+// /avatar-studio path to the native sculpting page, while the trait builder
+// this SDK talks to is the static build served alongside it.
+const DEFAULT_STUDIO_URL = 'https://three.ws/avatar-studio/index.html';
const DEFAULT_THREE_WS_ORIGIN = 'https://three.ws';
export class AvatarCreator {
/**
* @param {object} opts
* @param {HTMLElement} [opts.container] — DOM node to mount the modal into. Defaults to document.body.
- * @param {string} [opts.studioUrl] — URL of the Avatar Studio iframe. Defaults to https://three.ws/avatar-studio/.
+ * @param {string} [opts.studioUrl] URL of the Avatar Studio iframe. Defaults to https://three.ws/avatar-studio/index.html.
* @param {string} [opts.avaturnSessionUrl] — if provided, opens Avaturn in edit mode for that session.
* @param {(blob: Blob) => any} [opts.onExport] — called with the GLB Blob when the user exports.
* @param {() => any} [opts.onClose] — called when the user closes without exporting.
diff --git a/avatar-sdk/types/creator.d.ts b/avatar-sdk/types/creator.d.ts
index fed2af756..ac4dde5bc 100644
--- a/avatar-sdk/types/creator.d.ts
+++ b/avatar-sdk/types/creator.d.ts
@@ -1,7 +1,7 @@
export interface AvatarCreatorOptions {
/** DOM node to mount the modal in. Defaults to document.body. */
container?: HTMLElement;
- /** URL of the Avatar Studio iframe. Defaults to https://three.ws/avatar-studio/. */
+ /** URL of the Avatar Studio iframe. Defaults to https://three.ws/avatar-studio/index.html. */
studioUrl?: string;
/** Avaturn session URL for edit mode (created via /api/avatars/:id/session). */
avaturnSessionUrl?: string;
diff --git a/character-studio/README.md b/character-studio/README.md
index aff6c662a..b990c5874 100644
--- a/character-studio/README.md
+++ b/character-studio/README.md
@@ -12,13 +12,13 @@ Every three.ws agent needs an avatar, and not every user wants to generate one f
- **Embedded (primary):** the agent edit page opens it in a modal iframe via the Avatar Creator wrappers ([../src/avatar-creator.js](../src/avatar-creator.js) in-app, [../avatar-sdk/src/creator.js](../avatar-sdk/src/creator.js) in the published `@three-ws/avatar` SDK). The user clicks **Save Avatar** and the GLB is handed back to the host page.
- **Standalone demo:** mounted on the Avatar OS demo page at [three.ws/demo/avatar-os](https://three.ws/demo/avatar-os).
-- **In production** the compiled app is served same-origin under the `/avatar-studio/` path prefix. The root build copies [build/](build) into `dist/avatar-studio` via [../scripts/copy-avatar-studio.mjs](../scripts/copy-avatar-studio.mjs); the Vite `base` is pinned to `/avatar-studio/` in [vite.config.js](vite.config.js) so every emitted asset URL matches.
+- **In production** the compiled app is served same-origin under the `/avatar-studio/` path prefix, and its entry point is `https://three.ws/avatar-studio/index.html`. Address that index file, not the bare `/avatar-studio` path: the route table in [../vercel.json](../vercel.json) maps `/avatar-studio` and `/avatar-studio/` to the platform's separate native sculpting page, which does not speak the export contract below. The root build copies [build/](build) into `dist/avatar-studio` via [../scripts/copy-avatar-studio.mjs](../scripts/copy-avatar-studio.mjs); the Vite `base` is pinned to `/avatar-studio/` in [vite.config.js](vite.config.js) so every emitted asset URL matches.
## Install and run
```bash
cd character-studio
-npm install
+npm install # this directory is an npm workspace: the install runs at the repo root
npm run dev # Vite dev server on port 5173 (base path /avatar-studio/)
```
@@ -29,7 +29,8 @@ Other scripts:
```bash
npm run build # production build to ./build
npm run serve # preview the production build
-npm test # vitest (unit + integration, see tests/)
+npm run test:run # vitest once (unit + integration, see tests/)
+npm test # the same suite in watch mode
npm run lint # eslint + prettier
npm run get-assets # clone the upstream loot-assets trait library into public/
```
@@ -42,7 +43,7 @@ Environment variables (see [.env.example](.env.example)):
| Variable | Purpose |
|---|---|
-| `VITE_ASSET_PATH` | Root the app fetches `manifest.json` and trait assets from. Empty means same-origin, i.e. the files in [public/](public). |
+| `VITE_ASSET_PATH` | Root the app fetches `manifest.json` from. Unset means same-origin under the Vite base, i.e. `/avatar-studio/manifest.json` from [public/](public). |
| `VITE_OPENSEA_KEY` | OpenSea API key for the NFT trait-ownership checks. |
| `VITE_HELIUS_KEY` | Helius RPC key for the Solana flows. |
| `VITE_VALIDATION_SERVER_URL` | Mint validation server for the claim/mint pages. |
@@ -65,14 +66,16 @@ The engine lives in [src/library/](src/library) and has its own module index in
This is an application, not an npm library; nothing here is imported by other code. Its one public API is the postMessage contract a host page relies on when the app is embedded in an iframe. When `window.self !== window.top`, the export menu ([src/components/ExportMenu.jsx](src/components/ExportMenu.jsx)) replaces the GLB/VRM download buttons with a single **Save Avatar** button that posts the finished avatar to the parent window:
```js
-window.parent.postMessage(
- { source: 'characterstudio', type: 'export', format: 'glb', glb: arrayBuffer },
- '*',
- [arrayBuffer], // transferred, not copied
-);
+import { postAvatarToHost } from './library/embed-export'
+
+postAvatarToHost(arrayBuffer)
+// posts { source: 'characterstudio', type: 'export', format: 'glb', glb: arrayBuffer }
+// to window.parent with the buffer transferred, not copied
```
-`glb` is the binary glTF as a transferable `ArrayBuffer`. Standalone (top-level window), the same menu offers direct **GLB**, **VRM 0**, and **VRM 1** downloads instead.
+The envelope, the `characterstudio` source name, and the `window.self !== window.top` embed check all live in [src/library/embed-export.js](src/library/embed-export.js), which is the module to import (and the module the tests cover) rather than re-typing the message shape. `glb` is the binary glTF as a transferable `ArrayBuffer`.
+
+Standalone (top-level window), the same menu offers direct **GLB** and **VRM 0** downloads instead. There is no VRM 1 button: the VRM 1 exporter is broken upstream and [src/library/download-utils.js](src/library/download-utils.js) always falls back to the VRM 0 exporter.
## Example: receive an avatar from the embedded studio
@@ -95,7 +98,14 @@ await creator.open();
## Tests
-`npm test` runs the vitest suite in [tests/](tests) (unit tests for the library modules plus integration tests, jsdom environment). The root repo's `npm test` gate does not include this suite; run it here when touching this directory.
+`npm run test:run` runs the vitest suite in [tests/](tests) once (`npm test` is the same suite in watch mode). The root repo's `npm test` gate does not include this suite; run it here when touching this directory.
+
+- [tests/unit/export-contract.test.js](tests/unit/export-contract.test.js) covers the core path: a real three.js rigged mesh through `getGLBBlobData()` into valid binary glTF, and the embed envelope from `embed-export.js`.
+- [tests/unit/utils.test.js](tests/unit/utils.test.js) covers the shipped helpers in `src/library/utils.js`.
+- [tests/unit/i18n.test.js](tests/unit/i18n.test.js) covers translation lookups.
+- [tests/integration/](tests/integration) holds the input-validation and blockchain-input checks.
+
+[tests/setup.js](tests/setup.js) deliberately leaves `Blob`, `File` and `FileReader` to jsdom: three.js `GLTFExporter` reads its binary output through a `FileReader`, so a partial stub hangs every export test.
## Related surfaces
diff --git a/character-studio/index.html b/character-studio/index.html
index 488ea2d3b..a4c660d8d 100644
--- a/character-studio/index.html
+++ b/character-studio/index.html
@@ -31,7 +31,11 @@
<div id="root" style="overflow: hidden">
</div>
- <script src="/avatar-studio/ktx2/libktx.js"></script>
+ <!-- Relative on purpose. The dev server prefixes the Vite base onto any
+ root-relative src, so a literal /avatar-studio/... here is requested as
+ /avatar-studio/avatar-studio/... and 404s; this resolves next to the
+ served index in both dev and production. -->
+ <script src="./ktx2/libktx.js"></script>
<script type="module" src="src/Main.jsx"></script>
</body>
</html>
diff --git a/character-studio/src/App.jsx b/character-studio/src/App.jsx
index 7d2981fac..4e612ebf8 100644
--- a/character-studio/src/App.jsx
+++ b/character-studio/src/App.jsx
@@ -22,9 +22,11 @@ import Save from "./pages/Save"
import Wallet from "./pages/Wallet"
import Studio from "./pages/Studio"
-// dynamically import the manifest
-const assetImportPath = import.meta.env.VITE_ASSET_PATH + "/manifest.json"
-//const assetImportPath = "./manifest.json"
+// Dynamically import the manifest. VITE_ASSET_PATH points the app at an
+// external asset host; with it unset the manifest is same-origin, next to the
+// app under its Vite base (/avatar-studio/manifest.json in production).
+const assetRoot = (import.meta.env.VITE_ASSET_PATH || import.meta.env.BASE_URL || "/").replace(/\/$/, "")
+const assetImportPath = assetRoot + "/manifest.json"
const cameraDistanceOther = 6
const centerCameraTargetOther = new THREE.Vector3(0, 0.8, 0)
diff --git a/character-studio/src/components/AudioButton.module.css b/character-studio/src/components/AudioButton.module.css
index 3048a3e6e..0d4323e1a 100644
--- a/character-studio/src/components/AudioButton.module.css
+++ b/character-studio/src/components/AudioButton.module.css
@@ -30,10 +30,10 @@
}
.AudioOn {
- background-image: url('./ui/soundon.svg');
+ background-image: url('/ui/soundon.svg');
}
.AudioOff {
- background-image: url('./ui/soundoff.svg');
+ background-image: url('/ui/soundoff.svg');
}
diff --git a/character-studio/src/components/BackButton.module.css b/character-studio/src/components/BackButton.module.css
index cac3d2421..607a2949f 100644
--- a/character-studio/src/components/BackButton.module.css
+++ b/character-studio/src/components/BackButton.module.css
@@ -1,5 +1,5 @@
.StyledBackButton {
- background: url('./ui/backButton_gray.png') center center no-repeat;
+ background: url('/ui/backButton_gray.png') center center no-repeat;
background-size: 45% 55%;
height: 4em;
width: 4em;
@@ -19,6 +19,6 @@
.StyledBackButton:hover {
opacity: 1.0;
cursor: pointer;
- background: url('./ui/backButton_white.png') center center no-repeat;
+ background: url('/ui/backButton_white.png') center center no-repeat;
background-size: 45% 55%;
}
diff --git a/character-studio/src/components/BottomDisplayMenu.module.css b/character-studio/src/components/BottomDisplayMenu.module.css
index f47e91541..479b614f9 100644
--- a/character-studio/src/components/BottomDisplayMenu.module.css
+++ b/character-studio/src/components/BottomDisplayMenu.module.css
@@ -53,14 +53,14 @@
background-color: #1e2530;
}
.left-button{
- background: url('./ui/backButton_small.png');
+ background: url('/ui/backButton_small.png');
background-position: center;
background-repeat: no-repeat;
background-size: cover;
}
.right-button{
- background: url('./ui/nextButton_small.png');
+ background: url('/ui/nextButton_small.png');
background-position: center;
background-repeat: no-repeat;
background-size: cover;
diff --git a/character-studio/src/components/FloatingMenu.module.css b/character-studio/src/components/FloatingMenu.module.css
index c80b85e27..705667aea 100644
--- a/character-studio/src/components/FloatingMenu.module.css
+++ b/character-studio/src/components/FloatingMenu.module.css
@@ -128,14 +128,14 @@
background-color: #1e2530;
}
.left-button{
- background: url('./ui/backButton_small.png');
+ background: url('/ui/backButton_small.png');
background-position: center;
background-repeat: no-repeat;
background-size: cover;
}
.right-button{
- background: url('./ui/nextButton_small.png');
+ background: url('/ui/nextButton_small.png');
background-position: center;
background-repeat: no-repeat;
background-size: cover;
diff --git a/character-studio/src/components/JsonAttributes.module.css b/character-studio/src/components/JsonAttributes.module.css
index 6388ce5e7..28cf4d496 100644
--- a/character-studio/src/components/JsonAttributes.module.css
+++ b/character-studio/src/components/JsonAttributes.module.css
@@ -84,14 +84,14 @@
background-color: #1e2530;
}
.left-button{
- background: url('./ui/backButton_small.png');
+ background: url('/ui/backButton_small.png');
background-position: center;
background-repeat: no-repeat;
background-size: cover;
}
.right-button{
- background: url('./ui/nextButton_small.png');
+ background: url('/ui/nextButton_small.png');
background-position: center;
background-repeat: no-repeat;
background-size: cover;
diff --git a/character-studio/src/components/MergeOptions.module.css b/character-studio/src/components/MergeOptions.module.css
index 7956aebdb..4903112fa 100644
--- a/character-studio/src/components/MergeOptions.module.css
+++ b/character-studio/src/components/MergeOptions.module.css
@@ -52,14 +52,14 @@
background-color: #1e2530;
}
.left-button{
- background: url('./ui/backButton_small.png');
+ background: url('/ui/backButton_small.png');
background-position: center;
background-repeat: no-repeat;
background-size: cover;
}
.right-button{
- background: url('./ui/nextButton_small.png');
+ background: url('/ui/nextButton_small.png');
background-position: center;
background-repeat: no-repeat;
background-size: cover;
diff --git a/character-studio/src/components/ModelInformation.module.css b/character-studio/src/components/ModelInformation.module.css
index 312fd2124..e093975cb 100644
--- a/character-studio/src/components/ModelInformation.module.css
+++ b/character-studio/src/components/ModelInformation.module.css
@@ -89,14 +89,14 @@
background-color: #1e2530;
}
.left-button{
- background: url('./ui/backButton_small.png');
+ background: url('/ui/backButton_small.png');
background-position: center;
background-repeat: no-repeat;
background-size: cover;
}
.right-button{
- background: url('./ui/nextButton_small.png');
+ background: url('/ui/nextButton_small.png');
background-position: center;
background-repeat: no-repeat;
background-size: cover;
diff --git a/character-studio/src/components/token-box/TokenBox.module.css b/character-studio/src/components/token-box/TokenBox.module.css
index ce0e74ce4..738ffc86b 100644
--- a/character-studio/src/components/token-box/TokenBox.module.css
+++ b/character-studio/src/components/token-box/TokenBox.module.css
@@ -4,30 +4,6 @@
display: inline-block;
}
-.tokenBoxWrap .mask {
- width: 91%;
- height: 80%;
- overflow: hidden;
- -webkit-mask-image: url("./assets/backgrounds/token-frame-empty.svg");
- mask-image: url("./assets/backgrounds/token-frame-empty.svg");
- -webkit-mask-size: 100%;
- mask-size: 100%;
- -webkit-mask-repeat: no-repeat;
- mask-repeat: no-repeat;
- top: 50%;
- left: 50%;
- -ms-transform: translateX(-50%) translateY(-50%);
- -webkit-transform: translateX(-50%) translateY(-50%);
- transform: translateX(-50%) translateY(-50%);
- position: absolute;
- z-index: 0;
-}
-
-.tokenBoxWrap .mask canvas {
- width: 100% !important;
- height: 100% !important;
-}
-
.tokenBoxWrap .timer {
color: #ffffff;
position: absolute;
@@ -105,7 +81,7 @@
transform: translateX(-50%) translateY(-50%);
position: absolute;
display: block;
- background-image: url('./assets/backgrounds/token-box-none.svg');
+ background-image: url('/assets/backgrounds/token-box-none.svg');
}
.tokenBoxWrap .emptyIcon {
@@ -129,33 +105,33 @@
}
.tokenBoxWrap .frameActive {
- background-image: url('./assets/backgrounds/token-box-uncommon.svg');
+ background-image: url('/assets/backgrounds/token-box-uncommon.svg');
height: 116%;
width: 116%;
top: 50% !important;
}
.tokenBoxWrap .frame.mythic {
- background-image: url('./assets/backgrounds/token-box-uncommon.svg');
+ background-image: url('/assets/backgrounds/token-box-uncommon.svg');
}
.tokenBoxWrap .frame.epic {
- background-image: url('./assets/backgrounds/token-box-epic.svg');
+ background-image: url('/assets/backgrounds/token-box-epic.svg');
z-index: 1;
}
.tokenBoxWrap .frame.rare {
- background-image: url('./assets/backgrounds/token-box-rare.svg');
+ background-image: url('/assets/backgrounds/token-box-rare.svg');
}
.tokenBoxWrap .frame.uncommon {
- background-image: url('./assets/backgrounds/token-box-uncommon.svg');
+ background-image: url('/assets/backgrounds/token-box-uncommon.svg');
}
.tokenBoxWrap .frame.common {
- background-image: url('./assets/backgrounds/token-box-common.svg');
+ background-image: url('/assets/backgrounds/token-box-common.svg');
}
.tokenBoxWrap .frame.default {
- background-image: url('./assets/backgrounds/token-box-none.svg');
+ background-image: url('/assets/backgrounds/token-box-none.svg');
}
diff --git a/character-studio/src/pages/Create.module.css b/character-studio/src/pages/Create.module.css
index 791fae2a6..a95b6f69b 100644
--- a/character-studio/src/pages/Create.module.css
+++ b/character-studio/src/pages/Create.module.css
@@ -22,7 +22,7 @@
bottom:290px;
cursor: pointer;
background: rgba(5, 11, 14, 1);
- background-image: url('./ui/refresh.png');
+ background-image: url('/ui/refresh.png');
background-size: cover;
background-repeat: no-repeat;
z-index: 12;
diff --git a/character-studio/src/pages/Optimizer.module.css b/character-studio/src/pages/Optimizer.module.css
index d5647b1cc..e44d9752a 100644
--- a/character-studio/src/pages/Optimizer.module.css
+++ b/character-studio/src/pages/Optimizer.module.css
@@ -49,14 +49,14 @@
background-color: #1e2530;
}
.left-button{
- background: url('./ui/backButton_small.png');
+ background: url('/ui/backButton_small.png');
background-position: center;
background-repeat: no-repeat;
background-size: cover;
}
.right-button{
- background: url('./ui/nextButton_small.png');
+ background: url('/ui/nextButton_small.png');
background-position: center;
background-repeat: no-repeat;
background-size: cover;
diff --git a/docs/avatar-creation.md b/docs/avatar-creation.md
index f29dec1f0..1f63f9a75 100644
--- a/docs/avatar-creation.md
+++ b/docs/avatar-creation.md
@@ -84,7 +84,7 @@ Avatar Studio communicates with the parent app via `postMessage`. The message sh
[avatar-creator.js](../src/avatar-creator.js) listens for this, wraps the `ArrayBuffer` in a `Blob`, and passes it to `saveRemoteGlbToAccount()`.
-The avatar builder is served **same-origin** under `/avatar-studio` — the Vite dev middleware serves the character-studio build there in development, and the same build ships to that path in production, so the iframe resolves correctly on every deployment. Set the `VITE_CHARACTER_STUDIO_URL` environment variable to point the iframe at a standalone studio dev server (e.g. `http://localhost:5173`) instead.
+The avatar builder is served **same-origin** from `/avatar-studio/index.html`: the Vite dev middleware serves the character-studio build under that path in development, and the same build ships there in production, so the iframe resolves correctly on every deployment. The index file is named explicitly because the bare `/avatar-studio` path is routed to the native sculpting page. Set the `VITE_CHARACTER_STUDIO_URL` environment variable to point the iframe at a standalone studio dev server (e.g. `http://localhost:5173/avatar-studio/`) instead.
---
diff --git a/docs/character-studio.md b/docs/character-studio.md
index 76ccc57fb..99e695109 100644
--- a/docs/character-studio.md
+++ b/docs/character-studio.md
@@ -139,9 +139,11 @@ For developers who want to understand the internals or self-host:
The core of the system is `CharacterManager` in `character-studio/src/library/characterManager.js`. It orchestrates trait loading, mesh combining, animation playback, and VRM export. The UI layer communicates with it through React context (`SceneContext`, `ViewContext`).
-**Integration with the main app:** The `AvatarCreator` class in `src/avatar-creator.js` opens the builder in an iframe (served same-origin under `/avatar-studio`; the production build is mirrored into `dist/avatar-studio/` by the `copy-avatar-studio` Vite plugin, and the dev server serves `character-studio/build` at the same path) and listens for the `characterstudio` `postMessage` export event. When the user clicks Save Avatar inside the builder, the GLB bytes are passed back to the parent app.
+**Integration with the main app:** The `AvatarCreator` class in `src/avatar-creator.js` opens the builder in an iframe at `/avatar-studio/index.html` and listens for the `characterstudio` `postMessage` export event, which the builder sends from `character-studio/src/library/embed-export.js`. When the user clicks Save Avatar inside the builder, the GLB bytes are passed back to the parent app.
-**Build:** `npm run dev` inside `character-studio/` starts the dev server. `npm run build` outputs to `./build/`, which the main repo build copies into `dist/avatar-studio/`. Run `npm run get-assets` first to clone the required loot-assets into the public directory.
+The index file is addressed explicitly because the bare `/avatar-studio` path is routed to the native sculpting page; the trait builder is the static bundle beside it, mirrored into `dist/avatar-studio/` by the `copy-avatar-studio` Vite plugin and served from `character-studio/build` by the dev middleware.
+
+**Build:** `npm run dev` inside `character-studio/` starts the dev server on port 5173 at `/avatar-studio/`. `npm run build` outputs to `./build/`, which the main repo build copies into `dist/avatar-studio/`. `npm run test:run` runs the vitest suite once. In production the trait assets are mirrored same-origin through `GET /api/studio-assets/<path>`; `npm run get-assets` clones the same loot-assets library into the public directory for offline work.
---
diff --git a/prompts/swarm-100/sdk-character-studio.md b/prompts/swarm-100/sdk-character-studio.md
deleted file mode 100644
index 54b24d28e..000000000
--- a/prompts/swarm-100/sdk-character-studio.md
+++ /dev/null
@@ -1,89 +0,0 @@
-# Module audit: character-studio/
-
-How to run: paste this file's repo path into a fresh Claude Code chat in this
-repository and say "run this work order". This file is fully self-contained:
-it depends on no other prompt file anywhere. If neighboring files in
-prompts/swarm-100/ are gone, that work is done; if present, ignore them.
-Every claim below rots; step 0 re-measures, and what you measure wins.
-
-## Operating clause (binding)
-
-- Read CLAUDE.md first. Its rules override everything, including this file.
-- Finish 100% in this session. Never end the turn with a question, an option
- list, or an unexecuted plan. A judgment call goes in one line of the final
- report; it never becomes a question that halts work.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real
- funds or any irreversible on-chain write, git push or a production deploy,
- committing content that references a crypto project other than $THREE, and
- destroying unrecoverable data.
-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no
- commented-out code. Real APIs and real integrations only.
-- The em-dash and en-dash characters are banned in everything you write.
-- Concurrent agents share this worktree: stage explicit paths only (never a
- bare add-everything), and commit finished work promptly.
-- Before committing, run: npm run check:rules -- --paths <files you touched>.
- It must exit 0.
-
-## Step 0: re-derive the current state
-
-1. Read character-studio/README.md and character-studio/package.json (or the equivalent manifest).
-2. Find every consumer: grep the repo for imports of this module and check
- STRUCTURE.md for the surfaces it powers.
-
-## Task: bring character-studio/ to verified-shippable
-
-1. Build it with its own build script; the build must succeed from this
- worktree.
-2. Run its tests; add a core-path test if none proves the main export works.
-3. README quickstart: execute it verbatim as a new user would. Every command
- must run, every code sample must work. Fix drift in the same change.
-4. Public API: import the declared entry points with node and confirm they
- load. Exported functions the README documents must exist and behave as
- documented.
-5. Hard-rule scan across its source: no stubs, no mock data, no unfinished
- markers, no commented-out code.
-6. If this module publishes an artifact consumed elsewhere (a UMD bundle, a
- published npm package, a served static build), verify the wiring that
- produces the artifact still works; never hand-edit generated output.
-
-## Definition of done
-
-- [ ] Build green from this worktree.
-- [ ] Tests green, core path covered.
-- [ ] README quickstart executed successfully end to end.
-- [ ] Entry points import cleanly; documented API verified real.
-- [ ] Zero hard-rule violations remain in this module.
-- [ ] npm run check:rules -- --paths <touched files> exits 0.
-
-## Never blocked
-
-| Blocker | Resolution (act, do not ask) |
-|---|---|
-| Missing env var or credential | Check .env and .env.local, then the Cloud Run service env, then Secret Manager (the CLAUDE.md self-unblock playbook has the exact commands). If it truly exists nowhere, wire the code fully behind the env var, prove the wiring with a dry run, and name the single missing var in the report. |
-| gcloud not on PATH | Run: export PATH="$HOME/google-cloud-sdk/bin:$PATH" |
-| Dev server port 3000 busy | Another agent may be serving this repo; probe it and reuse if so. Otherwise start your own on a free port: npx vite --port 3101 |
-| Playwright browser missing | npx playwright install chromium |
-| A surface needs a signed-in user | Register a fresh account through the real /register flow against the real API and use it. Never mock the session. |
-| A defect sits in code you did not touch | Fix it if it blocks a Definition of done line (root cause it, never mask it). Otherwise note it in the report and continue. |
-| An unrelated test is red | Same rule. Never pipe npm test through tail; it masks exit codes. |
-
-## Close out (required)
-
-1. Verify every Definition of done line with the actual command output in
- front of you. Never claim a line you did not verify.
-2. Commit with explicit paths and a subject that describes the diff (house
- style: type(scope): what changed and why a reader cares).
-3. Delete this prompt file in that same commit:
-
- git rm prompts/swarm-100/sdk-character-studio.md
-
- The shrinking directory is this campaign's only progress ledger; there is
- no progress log to update.
-4. Final report: what step 0 measured, what changed (file list), evidence per
- Definition of done line, and any one-line judgment calls. No trailing
- questions, no unexecuted plans.
-
-If a line genuinely cannot pass inside this session (an external party must
-respond, or an owner-gated action is the final step), finish everything else,
-leave this file in place, and state exactly which line remains and who owns
-it. Never delete this file on a partial.
diff --git a/src/avatar-creator.js b/src/avatar-creator.js
index 33eaa5f87..cc9dd5f21 100644
--- a/src/avatar-creator.js
+++ b/src/avatar-creator.js
@@ -21,17 +21,19 @@ function getStudioUrl() {
.replace(/\/$/, '');
}
} catch (_) {}
- // Default: the Avatar Studio is served SAME-ORIGIN under /avatar-studio — the
- // Vite dev middleware serves character-studio/build there in dev, and the
- // copy-avatar-studio step ships the same build to /avatar-studio in prod
- // (see vite.config.js). Resolving to the live origin keeps this correct on
- // every deployment and avoids a dead localhost fallback in production. The
- // value must stay absolute: it's used as an iframe src and parsed with
- // `new URL(studioUrl).origin` for postMessage validation.
+ // Default: the trait builder is served SAME-ORIGIN from the static
+ // character-studio build (Vite dev middleware in dev, the
+ // copy-avatar-studio step into dist/avatar-studio in prod, see
+ // vite.config.js). Point at its index file explicitly: the bare
+ // /avatar-studio path is routed to the native sculpting page, which has no
+ // postMessage export contract. Resolving to the live origin keeps this
+ // correct on every deployment and avoids a dead localhost fallback in
+ // production. The value must stay absolute: it's used as an iframe src and
+ // parsed with `new URL(studioUrl).origin` for postMessage validation.
if (typeof location !== 'undefined' && location.origin) {
- return `${location.origin}/avatar-studio`;
+ return `${location.origin}/avatar-studio/index.html`;
}
- return 'https://three.ws/avatar-studio';
+ return 'https://three.ws/avatar-studio/index.html';
}
export class AvatarCreator {
diff --git a/src/demo/os-studio.js b/src/demo/os-studio.js
index 40772e59b..b8035c110 100644
--- a/src/demo/os-studio.js
+++ b/src/demo/os-studio.js
@@ -28,15 +28,17 @@ const PUBLIC_STUDIO = 'https://m3-org.github.io/CharacterStudio';
// Same resolution as getStudioUrl() in src/avatar-creator.js: an explicit
// VITE_CHARACTER_STUDIO_URL override wins (e.g. a standalone studio dev server
// on :5173 during character-studio development); otherwise the Avatar Studio is
-// served same-origin under /avatar-studio — by the Vite dev middleware in dev
-// and the copy-avatar-studio build step in prod (see vite.config.js) — so this
-// resolves to a live URL on every deployment instead of a dead localhost.
+// served same-origin from the static character-studio build (Vite dev
+// middleware in dev, the copy-avatar-studio build step in prod, see
+// vite.config.js), addressed by its index file because the bare /avatar-studio
+// path belongs to the native sculpting page. This resolves to a live URL on
+// every deployment instead of a dead localhost.
function resolveStudioUrl() {
try {
const override = import.meta.env?.VITE_CHARACTER_STUDIO_URL;
if (override) return String(override).trim().replace(/\/$/, '');
} catch (_) {}
- return `${location.origin}/avatar-studio`;
+ return `${location.origin}/avatar-studio/index.html`;
}
const STUDIO_URL = resolveStudioUrl();