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(scene-studio): Agent tab drives the open scene by prompt, Nodes tab edits TSL material graphs

nirholas18a63e18a3a8
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c040e3148..b5139a7b3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **Every generated and purchased model now ships with a signed provenance credential, free, by default**: Content credentials (specs/PROVENANCE_3D.md) used to be an on-demand, Claude-track action: you had to call anchor_provenance to get one. Now every GLB the Forge produces, across every generation lane (free NIM, Forge Pro, rigged avatars, self-host TRELLIS/Hunyuan, async GCP workers), gets an ed25519-signed content credential the moment it's materialized, and every first download of a paid asset from the x402 asset bazaar gets one too, with the hash and a verify link returned right in the download response. Signing and storage are free and local, no Solana write and no spend, so there's nothing to gate; the separate paid anchor_provenance upgrade, which additionally commits the hash on-chain, is untouched and still available. A credential is keyed by content hash, so it's issued exactly once per file no matter how many times a lane or endpoint touches it. Model pages now show the same verified / tampered / unverified badge the 3D viewer already had, and a third party can check any model for free with GET /api/provenance. The owner can turn automatic issuance off platform-wide with PROVENANCE_AUTO_DISABLE=true; nothing else about verification changes if they do. (`/docs/provenance`) `[feature, security]`
- **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]`
+- **Scene Studio: an Agent tab that edits your open scene by prompt, plus a TSL node material editor**: Scene Studio's sidebar grows two tabs. Agent is a chat panel that reads the open scene and drives it with the same real editor.execute(Command) calls the toolbar and menus use (free, keyless, rate-limited model via POST /api/scene/agent): add a primitive or a Forge-generated object, move/rotate/scale a named object, recolor a material. Every mutating prompt pushes a numbered version (a scene snapshot plus a viewport screenshot); clicking an earlier version restores it as one more undoable edit, so a bad restore is one Ctrl+Z away like any other mistake. Nodes is a dropdown-wired TSL (Three.js Shading Language) material graph editor for the selected object: build a graph from UV, time, color, texture, and math nodes as a reorderable card list, no canvas or wires to route, and apply it to swap in a real node material through the same undo-able command path. Fixed along the way: restoring a version used to append the snapshot's objects on top of the current scene instead of replacing them (SetSceneCommand, the vendored editor's own scene-import command, only ever adds); and the site-wide corner-stack widget could sit on top of the Agent tab's version-restore buttons and eat the click, now suppressed while the studio is open. (`/scene`) `[feature, fix]`
- **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.md
index bd2776077..a27b2840b 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -57,7 +57,7 @@ bottom.
| Onboarding tier (Simple ⇄ Everything) | Menu tags [public/nav-data.js](public/nav-data.js), runtime + `window.twsTier` [public/nav.js](public/nav.js), styles [public/nav.css](public/nav.css), homepage start path + gate [pages/home.html](pages/home.html) + [public/home.css](public/home.css) | Live | Progressive disclosure for first-time visitors: the platform's ~119 nav destinations and ten deep homepage sections were competing with its core promise, so a new visitor now gets the ~28 links and the sections that carry one journey (make an avatar, build an agent, publish it) with a three-step start path under the hero. Everything else (the whole Launch menu, trading, token economy, Oracle, pay-per-call, dev platform, the stack) is tagged `tier: 'advanced'` / `data-tier="advanced"` and revealed by one control. Mechanism is one `<html>` class (`tws-lite`) over one localStorage key (`tws:tier`), applied pre-paint and never re-rendered (the nav binds document-level listeners once), with the two surfaces synced through a `tws:tier-change` event. Deep links into a gated section reveal it for that visit. Nothing is removed, only deferred. Docs: [docs/onboarding-tier.md](docs/onboarding-tier.md). Tests: [tests/onboarding-tier.test.js](tests/onboarding-tier.test.js) |
| Tour Builder (no-code playground) | [pages/tour-builder.html](pages/tour-builder.html) `→ /tour-builder` | Live | Point-and-click editor over a demo storefront: pick avatar, add stops, preview the real tour, export curriculum + Shopify snippets. Also ships **Templates** — ready-made tours (Sperax's DeFi protocol tour is the first) that load straight into the editor. Logic: [public/tour-builder/builder.js](public/tour-builder/builder.js), presets: [public/tour-builder/presets/](public/tour-builder/presets). Sperax template doc: [docs/tutorials/sperax-tour.md](docs/tutorials/sperax-tour.md) |
| Avatar builder (full app) | [character-studio/](character-studio) | Fork of [m3-org/CharacterStudio](https://github.com/M3-org/CharacterStudio), MIT, see [character-studio/LICENSE](character-studio/LICENSE) | Web-first character creator |
-| Scene Studio (3D scene editor) | [src/scene-studio/](src/scene-studio) `→ /scene`: boot [main.js](src/scene-studio/main.js), shared GLB loader [loader.js](src/scene-studio/loader.js), action bar [actions.js](src/scene-studio/actions.js), first-run overlay [empty-state.js](src/scene-studio/empty-state.js), icon-button labels [toolbar-a11y.js](src/scene-studio/toolbar-a11y.js), chrome [studio.css](src/scene-studio/studio.css) | Vendored [mrdoob/three.js](https://github.com/mrdoob/three.js) r184 editor, MIT, see [src/scene-studio/vendor/README.md](src/scene-studio/vendor/README.md) | Import GLBs, compose scenes, edit materials/lights, export. The sibling modules never touch `vendor/**`: they add the Import-from-Forge / Export-presets / Share bar (which docks beside the resizable sidebar rather than over its tabs), the empty-state card a brand-new scene needs, accessible names plus `aria-pressed` on the icon-only translate/rotate/scale buttons and names on the animation timeline's play/pause/stop transport, and toast-based failures in place of native `alert()`/`prompt()`. Below 600px the sidebar dock drops the vendored `.TabbedPanel` 335px floor so it fits a 320px screen instead of hanging 15px off it, and the empty-state card starts below the action bar and caps itself at the viewport region. Pinned under the nav by `--nav-h` (the real injected-header height), not `--header-h`. Deep links: `?model=<glb_url>`, `?handoff=1` from `/pose`, `#file=<url>`. Docs: [docs/scene-studio.md](docs/scene-studio.md), [src/scene-studio/README.md](src/scene-studio/README.md). Tests: [tests/scene-studio-actions.test.js](tests/scene-studio-actions.test.js) |
+| Scene Studio (3D scene editor) | [src/scene-studio/](src/scene-studio) `→ /scene`: boot [main.js](src/scene-studio/main.js), shared GLB loader [loader.js](src/scene-studio/loader.js), action bar [actions.js](src/scene-studio/actions.js), Agent chat tab [agent-tab.js](src/scene-studio/agent-tab.js) + its endpoint [api/scene/agent.js](api/scene/agent.js), TSL material graph tab [tsl-editor.js](src/scene-studio/tsl-editor.js), first-run overlay [empty-state.js](src/scene-studio/empty-state.js), icon-button labels [toolbar-a11y.js](src/scene-studio/toolbar-a11y.js), chrome [studio.css](src/scene-studio/studio.css) | Vendored [mrdoob/three.js](https://github.com/mrdoob/three.js) r184 editor, MIT, see [src/scene-studio/vendor/README.md](src/scene-studio/vendor/README.md) | Import GLBs, compose scenes, edit materials/lights, export. The sibling modules never touch `vendor/**`: they add the Import-from-Forge / Export-presets / Share bar (which docks beside the resizable sidebar rather than over its tabs), the empty-state card a brand-new scene needs, accessible names plus `aria-pressed` on the icon-only translate/rotate/scale buttons and names on the animation timeline's play/pause/stop transport, and toast-based failures in place of native `alert()`/`prompt()`. Below 600px the sidebar dock drops the vendored `.TabbedPanel` 335px floor so it fits a 320px screen instead of hanging 15px off it, and the empty-state card starts below the action bar and caps itself at the viewport region. Pinned under the nav by `--nav-h` (the real injected-header height), not `--header-h`. Two added sidebar tabs: **Agent** drives the open scene by prompt through a free, keyless, rate-limited tool-calling model, executing real `editor.execute(Command)`s and pushing an undoable, screenshotted version per mutating turn; **Nodes** is a dropdown-wired TSL material graph editor for the selected object, no node canvas. The studio adds `tws-modal-open` to `<body>` so the site-wide corner-stack widgets ([public/corner-stack.js](public/corner-stack.js)) don't float on top of its controls. Deep links: `?model=<glb_url>`, `?handoff=1` from `/pose`, `#file=<url>`. Docs: [docs/scene-studio.md](docs/scene-studio.md), [src/scene-studio/README.md](src/scene-studio/README.md). Tests: [tests/scene-studio-actions.test.js](tests/scene-studio-actions.test.js), [tests/scene-studio-agent-restore.test.js](tests/scene-studio-agent-restore.test.js) |
| Diorama (text → 3D world) | [src/diorama/](src/diorama) `→ /diorama` | In-repo · backend [api/diorama.js](api/diorama.js) | One sentence → an explorable 3D diorama: Claude composes the scene, each object is forged to a real GLB, assembled live, saved to a public gallery + shareable permalink |
| Workbench (image → 3D workflows) | Page [pages/workbench.html](pages/workbench.html) `→ /workbench` + [src/workbench/](src/workbench): controller [main.js](src/workbench/main.js), viewport [viewport.js](src/workbench/viewport.js), in-browser mesh ops [mesh-tools.js](src/workbench/mesh-tools.js), node model [workflows.js](src/workbench/workflows.js), runner [runner.js](src/workbench/runner.js), graph editor [graph-editor.js](src/workbench/graph-editor.js), API client [api.js](src/workbench/api.js) | Live | A desktop-style workspace: icon rail (Generate, Workflows, Extensions, Settings), a workflow panel of node cards, and a viewport with undo/redo, import, GLB/OBJ/STL/PLY export, smooth, decimate and free memory. Workflows are typed image/mesh chains saved per browser and edited in a node graph; they run against the real Forge endpoints (`/api/forge`, `/api/forge-rembg`, `/api/forge-remesh`, `/api/forge?action=rig`, `/api/material-studio`), checkpointing in-browser edits to durable storage before any server step. Extensions reads the live engine catalog and lane health. Docs: [docs/workbench.md](docs/workbench.md) |
| Modly (local GPU generation + Modly app integrations) | Hub page [pages/modly.html](pages/modly.html) `→ /modly` + [src/modly-page.js](src/modly-page.js); shared local client [src/modly-local.js](src/modly-local.js); Forge "Use your GPU" lane [src/forge-modly.js](src/forge-modly.js) wired in [src/forge.js](src/forge.js) `→ /forge`; desktop app [apps/forge-desktop/](apps/forge-desktop); Modly extensions [integrations/modly/](integrations/modly) | Live (web); desktop app and extensions in-repo | Builds on Modly (MIT, Lightning Pixel). Browser surfaces talk to the visitor's own Modly on localhost only after Connect, run its image-to-3D models with real progress and cancel, and copy results to storage so rig/optimize/AR work. Modly users get three.ws cloud nodes and publishing. Docs: [docs/modly.md](docs/modly.md). Tests: tests/modly-local.test.js, integrations/modly/tests/ |
diff --git a/api/_lib/rate-limit.js b/api/_lib/rate-limit.js
index c1553200e..233b468c7 100644
--- a/api/_lib/rate-limit.js
+++ b/api/_lib/rate-limit.js
@@ -2354,6 +2354,14 @@ export const limits = {
// minute per account; the limit comes from the plan config, so each plan
// gets its own bucket name and the memo in getLimiter keys on the limit too.
devPlanBurst: (planId, key, { limit }) => getLimiter(`devplan:burst:${planId}`, { limit, window: '1 m' }).limit(key),
+ // Scene Studio Agent tab (api/scene/agent.js): free, anonymous, tool-calling
+ // round the browser drives one turn at a time. Same shape as concierge: a
+ // per-IP lane plus a global ceiling on the free-tier draw, both critical so a
+ // Redis outage fails closed rather than handing out unbounded free inference.
+ sceneAgentIp: (ip) =>
+ getLimiter('scene:agent:ip', { limit: 20, window: '1 m', critical: true }).limit(ip),
+ sceneAgentGlobal: () =>
+ getLimiter('scene:agent:global', { limit: 600, window: '1 m', critical: true }).limit('global'),
};
// Fixed-window counters for limits.planApi. One small record per principal, so
diff --git a/api/scene/agent.js b/api/scene/agent.js
new file mode 100644
index 000000000..dde9266ac
--- /dev/null
+++ b/api/scene/agent.js
@@ -0,0 +1,88 @@
+// POST /api/scene/agent
+//
+// One reasoning round for the Scene Studio "Agent" tab (src/scene-studio/agent-tab.js).
+// The browser owns the scene and every tool execution: this endpoint only picks a
+// model off the free-first tool-calling chain (api/_lib/llm-tool-chain.js), sends
+// it the running transcript plus the caller's own tool definitions, and returns
+// the assistant's text and/or requested tool_calls verbatim.
+//
+// Same shape as api/concierge.js on purpose: free, public, anonymous, CORS `*`,
+// its own IP + global rate buckets (limits.sceneAgentIp / sceneAgentGlobal) so a
+// busy studio session can never starve signed-in chat or the embeddable widget.
+// Unlike concierge this DOES take tools, reusing the client-tool-round building
+// blocks (api/_lib/client-tool-round.js) that already validate an OpenAI-shaped
+// tool list and a bounded message transcript for the metered /api/v1 lane, the
+// same validation, just answered as plain JSON instead of billed SSE, since the
+// studio executes tools locally and only needs the next round's result.
+import { z } from 'zod';
+import { cors, json, method, readJson, wrap, error, rateLimited } from '../_lib/http.js';
+import { parse } from '../_lib/validate.js';
+import { limits, clientIp } from '../_lib/rate-limit.js';
+import { providerChain } from '../_lib/llm-tool-chain.js';
+import { clientToolRound, sanitizeClientMessages, normalizeClientTools, ClientToolError } from '../_lib/client-tool-round.js';
+import { recordEvent } from '../_lib/usage.js';
+import { captureException } from '../_lib/sentry.js';
+
+export const maxDuration = 60;
+
+const MAX_TOKENS = 1024;
+
+const bodySchema = z.object({
+ messages: z.array(z.record(z.any())).min(1).max(200),
+ tools: z.array(z.record(z.any())).min(1).max(32),
+});
+
+export default wrap(async (req, res) => {
+ if (cors(req, res, { origins: '*', methods: 'POST,OPTIONS' })) return;
+ if (!method(req, res, ['POST'])) return;
+
+ const body = parse(bodySchema, await readJson(req));
+ const ip = clientIp(req);
+ const rl = await limits.sceneAgentIp(ip);
+ if (!rl.success) return rateLimited(res, rl, 'too many agent turns from this connection, try again shortly');
+ const gl = await limits.sceneAgentGlobal();
+ if (!gl.success) return rateLimited(res, gl, 'the scene agent is at capacity, try again in a moment');
+
+ let messages;
+ let tools;
+ try {
+ messages = sanitizeClientMessages(body.messages);
+ tools = normalizeClientTools(body.tools);
+ } catch (err) {
+ if (err instanceof ClientToolError) return error(res, err.status, err.code, err.message);
+ throw err;
+ }
+
+ const started = Date.now();
+ const chain = providerChain();
+ if (!chain.length) return error(res, 503, 'llm_unavailable', 'No scene agent model is configured right now.');
+
+ let out;
+ try {
+ out = await clientToolRound({ messages, tools, maxTokens: MAX_TOKENS, temperature: 0.2, chain });
+ } catch (err) {
+ captureException(err, { route: 'scene/agent', stage: 'round' });
+ return error(res, err?.status === 503 ? 503 : 502, err?.code || 'upstream_error', 'The scene agent could not reach a model this turn. Try again.');
+ }
+
+ recordEvent({
+ userId: null,
+ kind: 'chat',
+ tool: 'scene-agent',
+ latencyMs: Date.now() - started,
+ meta: {
+ provider: out.provider,
+ model: out.model,
+ anonymous: true,
+ tool_calls: out.toolCalls.length,
+ history_turns: messages.length,
+ },
+ });
+
+ return json(res, 200, {
+ content: out.content || null,
+ tool_calls: out.toolCalls.map((tc) => ({ id: tc.id, name: tc.name, arguments: tc.args || '{}' })),
+ provider: out.provider,
+ model: out.model,
+ });
+});
diff --git a/data/changelog.json b/data/changelog.json
index 0deeb0b99..309c2455d 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": "Scene Studio: an Agent tab that edits your open scene by prompt, plus a TSL node material editor",
+ "link": "/scene",
+ "summary": "Scene Studio's sidebar grows two tabs. Agent is a chat panel that reads the open scene and drives it with the same real editor.execute(Command) calls the toolbar and menus use (free, keyless, rate-limited model via POST /api/scene/agent): add a primitive or a Forge-generated object, move/rotate/scale a named object, recolor a material. Every mutating prompt pushes a numbered version (a scene snapshot plus a viewport screenshot); clicking an earlier version restores it as one more undoable edit, so a bad restore is one Ctrl+Z away like any other mistake. Nodes is a dropdown-wired TSL (Three.js Shading Language) material graph editor for the selected object: build a graph from UV, time, color, texture, and math nodes as a reorderable card list, no canvas or wires to route, and apply it to swap in a real node material through the same undo-able command path. Fixed along the way: restoring a version used to append the snapshot's objects on top of the current scene instead of replacing them (SetSceneCommand, the vendored editor's own scene-import command, only ever adds); and the site-wide corner-stack widget could sit on top of the Agent tab's version-restore buttons and eat the click, now suppressed while the studio is open.",
+ "tags": [
+ "feature",
+ "fix"
+ ]
+ },
{
"date": "2026-10-12",
"title": "Every generated and purchased model now ships with a signed provenance credential, free, by default",
diff --git a/docs/scene-studio.md b/docs/scene-studio.md
index 6bfa5e4af..79ac03f9c 100644
--- a/docs/scene-studio.md
+++ b/docs/scene-studio.md
@@ -20,13 +20,23 @@ The editor is ported from the upstream `editor/index.html` with a small set of l
### The three.ws layer
-Four sibling modules sit on top of the vendored editor without touching `vendor/**`. They are the difference between a mirror of the upstream demo and a surface that belongs to this platform:
+Six sibling modules sit on top of the vendored editor without touching `vendor/**`. They are the difference between a mirror of the upstream demo and a surface that belongs to this platform:
- **A quick-action bar** (top right, clear of the sidebar): **Import from Forge** takes a GLB URL from a [Forge](./forge.md) or Forge Max result and adds it through the same undo-able path as a drag-and-drop import; **Export** writes a Web GLB or an AR bundle (`.usdz` for iOS Quick Look) in one click; **Share** uploads the scene and opens the platform's "Embed this model" panel with an iframe, web-component, and `<agent-3d>` snippet.
- **An empty state.** A brand-new scene holds nothing but the default camera, which renders as a bare grid. The overlay on that grid says what a starting point looks like (drag a `.glb` in, pick a primitive from **Add**, or import a model you already generated) and retires itself the moment the scene has content, including a scene restored from autosave.
- **Designed failures.** A dead link, a private URL, a blocked cross-origin fetch, or a failed upload each surface in the platform's toast with the likely cause named and a fallback to try, rather than in a native `alert()` box.
- **Accessible icon-only controls.** The vendored translate/rotate/scale gizmo buttons and the animation timeline's play/pause/stop transport are icon-only `<button>`s with no accessible name. The studio gives all six names read from the editor's own string table, so they stay translated, and mirrors the active gizmo mode into `aria-pressed` so it is both announced and reachable by keyboard.
+### Agent tab
+
+A fifth sibling module, the **Agent** tab in the sidebar, lets you drive the open scene by typing instead of clicking. It is a small chat panel next to the vendored Scene/Project/Settings tabs. Type a prompt ("add a red cube to the left of the chair", "make the sphere metallic"), and a free, keyless model (the same free-first provider chain the rest of the platform's chat surfaces use, see [docs/free-llm-providers.md](./free-llm-providers.md)) reads the scene and calls real editing tools: add a primitive or a Forge-generated object, move/rotate/scale a named object, or recolor a material. Every tool call runs as a genuine `editor.execute(Command)`, the exact call the toolbar and menus make, so it shows up in the hierarchy, undoes with Edit > Undo, and persists through the same autosave as a manual edit.
+
+Every prompt that changes the scene pushes a numbered **version**: a snapshot of the scene plus a screenshot of the viewport at that moment, so you can see what changed without hunting through the hierarchy. Click an earlier version's thumbnail to restore it; that restore is itself one more undoable edit; a mis-restore is one Ctrl+Z away, same as any other mistake in the editor.
+
+### Nodes tab (TSL material graph)
+
+The sixth sibling module is the **Nodes** tab: a node-based material editor for [TSL](https://github.com/mrdoob/three.js/wiki/Three.js-Shading-Language) (Three.js Shading Language), the node system that backs three.js's `WebGPURenderer` and WebGPU-capable `MeshStandardNodeMaterial`. Build a graph for the selected object's material from UV, time, color, texture, and math nodes; each node is a card with dropdown inputs referencing other nodes by label, so there is no canvas to pan or wires to route, just a reorderable list that stays readable at any zoom level. Applying the graph swaps the object's material for a node material wired to the graph's output, through the same undo-able command path as every other material edit.
+
### Handoff from Animation Studio
Scene Studio is the render target for animations built in [Animation Studio](./animation-studio.md). When you click "Open in Scene Studio" there, the studio bakes your keyframed animation into a GLB, stashes it in IndexedDB, and navigates to `/scene?handoff=1`. Scene Studio picks the model up on boot (`takeSceneHandoff`), drops it into the scene with its animation track ready, and you record it to video from the editor's render menu. The GLB is passed through browser storage, not the network, so nothing large is uploaded to move a model between the two tools.
@@ -69,4 +79,5 @@ A typical round trip from another studio:
- [Animation Studio](./animation-studio.md): builds the animated GLBs Scene Studio records to video.
- [Restyle Studio](./restyle.md): re-skin the models before or after composing them.
- [3D asset pipeline](./3d-asset-pipeline.md): how GLB, glTF, and clip formats relate across the platform.
+- [Free LLM providers](./free-llm-providers.md): the free-first provider chain the Agent tab reasons with.
- [src/scene-studio/README.md](../src/scene-studio/README.md): the module layout, the exported wrapper API, and how re-vendoring a three.js upgrade stays mechanical.
diff --git a/public/changelog-recent.json b/public/changelog-recent.json
index 5c2890f7c..c243f860a 100644
--- a/public/changelog-recent.json
+++ b/public/changelog-recent.json
@@ -1,11 +1,11 @@
{
- "generated_at": "2026-10-12T09:45:15.975Z",
+ "generated_at": "2026-10-12T10:51:38.414Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
"url": "https://three.ws"
},
- "total": 4044,
+ "total": 4045,
"complete": false,
"full_feed": "/changelog.json",
"entries": [
@@ -103,6 +103,17 @@
"improvement"
]
},
+ {
+ "date": "2026-10-12",
+ "type": "update",
+ "title": "Scene Studio: an Agent tab that edits your open scene by prompt, plus a TSL node material editor",
+ "summary": "Scene Studio's sidebar grows two tabs. Agent is a chat panel that reads the open scene and drives it with the same real editor.execute(Command) calls the toolbar and menus use (free, keyless, rate-limited model via POST /api/scene/agent): add a primitive or a Forge-generated object, move/rotate/scale a named object, recolor a material. Every mutating prompt pushes a numbered version (a scene snapshot plus a viewport screenshot); clicking an earlier version restores it as one more undoable edit, so a bad restore is one Ctrl+Z away like any other mistake. Nodes is a dropdown-wired TSL (Three.js Shading Language) material graph editor for the selected object: build a graph from UV, time, color, texture, and math nodes as a reorderable card list, no canvas or wires to route, and apply it to swap in a real node material through the same undo-able command path. Fixed along the way: restoring a version used to append the snapshot's objects on top of the current scene instead of replacing them (SetSceneCommand, the vendored editor's own scene-import command, only ever adds); and the site-wide corner-stack widget could sit on top of the Agent tab's version-restore buttons and eat the click, now suppressed while the studio is open.",
+ "link": "/scene",
+ "tags": [
+ "feature",
+ "fix"
+ ]
+ },
{
"date": "2026-10-12",
"type": "update",
@@ -1537,16 +1548,6 @@
"tags": [
"launch"
]
- },
- {
- "date": "2026-10-09",
- "type": "launch",
- "title": "Modly: 3D on Your Own GPU",
- "summary": "Connect the free, open-source Modly app on your computer and turn an image or a prompt into a 3D model on your own graphics card. Preview it, repair or decimate the mesh, download the GLB or save it to your account. Also the hub for the Forge GPU lane, the three.ws Forge desktop app and the Modly extensions.",
- "link": "/modly",
- "tags": [
- "launch"
- ]
}
]
}
diff --git a/public/changelog.json b/public/changelog.json
index b0708f855..c2de191b9 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-10-12T09:45:15.950Z",
+ "generated_at": "2026-10-12T10:51:38.392Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -100,6 +100,17 @@
"improvement"
]
},
+ {
+ "date": "2026-10-12",
+ "type": "update",
+ "title": "Scene Studio: an Agent tab that edits your open scene by prompt, plus a TSL node material editor",
+ "summary": "Scene Studio's sidebar grows two tabs. Agent is a chat panel that reads the open scene and drives it with the same real editor.execute(Command) calls the toolbar and menus use (free, keyless, rate-limited model via POST /api/scene/agent): add a primitive or a Forge-generated object, move/rotate/scale a named object, recolor a material. Every mutating prompt pushes a numbered version (a scene snapshot plus a viewport screenshot); clicking an earlier version restores it as one more undoable edit, so a bad restore is one Ctrl+Z away like any other mistake. Nodes is a dropdown-wired TSL (Three.js Shading Language) material graph editor for the selected object: build a graph from UV, time, color, texture, and math nodes as a reorderable card list, no canvas or wires to route, and apply it to swap in a real node material through the same undo-able command path. Fixed along the way: restoring a version used to append the snapshot's objects on top of the current scene instead of replacing them (SetSceneCommand, the vendored editor's own scene-import command, only ever adds); and the site-wide corner-stack widget could sit on top of the Agent tab's version-restore buttons and eat the click, now suppressed while the studio is open.",
+ "link": "/scene",
+ "tags": [
+ "feature",
+ "fix"
+ ]
+ },
{
"date": "2026-10-12",
"type": "update",
diff --git a/public/changelog.xml b/public/changelog.xml
index d44c8cc0c..76052c068 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -78,6 +78,14 @@
<category>feature</category>
<description>Material Studio's AI restyle and seeded colorway variants, plus Restyle Studio's HoloPart &quot;Regenerate part&quot; 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 &quot;Diff&quot; 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>Scene Studio: an Agent tab that edits your open scene by prompt, plus a TSL node material editor</title>
+ <link>https://three.ws/scene</link>
+ <guid isPermaLink="false">2026-10-12:Scene Studio: an Agent tab that edits your open scene by prompt, plus a TSL node material editor</guid>
+ <pubDate>Mon, 12 Oct 2026 12:00:00 GMT</pubDate>
+ <category>feature</category>
+ <description>Scene Studio's sidebar grows two tabs. Agent is a chat panel that reads the open scene and drives it with the same real editor.execute(Command) calls the toolbar and menus use (free, keyless, rate-limited model via POST /api/scene/agent): add a primitive or a Forge-generated object, move/rotate/scale a named object, recolor a material. Every mutating prompt pushes a numbered version (a scene snapshot plus a viewport screenshot); clicking an earlier version restores it as one more undoable edit, so a bad restore is one Ctrl+Z away like any other mistake. Nodes is a dropdown-wired TSL (Three.js Shading Language) material graph editor for the selected object: build a graph from UV, time, color, texture, and math nodes as a reorderable card list, no canvas or wires to route, and apply it to swap in a real node material through the same undo-able command path. Fixed along the way: restoring a version used to append the snapshot's objects on top of the current scene instead of replacing them (SetSceneCommand, the vendored editor's own scene-import command, only ever adds); and the site-wide corner-stack widget could sit on top of the Agent tab's version-restore buttons and eat the click, now suppressed while the studio is open.</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.json
index b67a9e67b..05804ea91 100644
--- a/public/features.json
+++ b/public/features.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-10-12T09:45:15.934Z",
+ "generated_at": "2026-10-12T10:51:38.378Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json",
"site": {
"name": "three.ws",
diff --git a/src/scene-studio/README.md b/src/scene-studio/README.md
index b79c4f266..59e9b48a6 100644
--- a/src/scene-studio/README.md
+++ b/src/scene-studio/README.md
@@ -34,6 +34,11 @@ src/scene-studio/
├── loader.js Shared GLB loader: Draco/KTX2/Meshopt-wired GLTFLoader that
│ adds a parsed GLB through the undo-able AddObjectCommand path
├── actions.js Layered action bar: Import from Forge, Export presets, Share
+├── agent-tab.js Agent sidebar tab: chat panel that drives the open scene
+│ through real editor.execute(Command) tool calls, with a
+│ screenshot + undoable version per mutating prompt
+├── tsl-editor.js Nodes sidebar tab: dropdown-wired TSL material graph editor
+│ for the selected object
├── empty-state.js First-run overlay over the empty grid, retires on first object
├── remote-scene.js Strips scripts and history from a scene opened by #file= link
├── toolbar-a11y.js Accessible names for the icon-only controls: the transform
@@ -107,7 +112,7 @@ affordances the stock File and Export menus do not offer on their own:
## Exports
-The wrappers export seven functions; `main.js` is entry-only and exports nothing.
+The wrappers export nine functions; `main.js` is entry-only and exports nothing.
| Module | Export | What it does |
| --- | --- | --- |
@@ -119,6 +124,8 @@ The wrappers export seven functions; `main.js` is entry-only and exports nothing
| `empty-state.js` | `mountEmptyState(editor, container)` | Mounts the first-run overlay and keeps it in sync with the scene graph. Returns the overlay element. |
| `toolbar-a11y.js` | `enhanceToolbarA11y(editor, toolbarDom)` | Labels the vendored translate/rotate/scale buttons and mirrors their `selected` class into `aria-pressed`. Returns the labelled buttons. |
| `toolbar-a11y.js` | `enhanceAnimationA11y(editor, animationDom)` | Labels the vendored animation timeline's play/pause/stop transport, which ships as three identical unnamed icon buttons. Matches each one on the SVG shape the vendor draws, not on child order, so a control added to that panel can never inherit the wrong label. Returns the labelled buttons. |
+| `agent-tab.js` | `createAgentPanel(editor)` | Builds the Agent sidebar tab: a chat panel that posts each turn to [api/scene/agent.js](../../api/scene/agent.js), executes the model's tool calls as real `editor.execute(Command)`s, and pushes a scene+screenshot version per mutating prompt. Returns a `UIElement` ready for `sidebar.addTab('agent', 'Agent', panel)`. |
+| `tsl-editor.js` | `createTslEditorPanel(editor)` | Builds the Nodes sidebar tab: a dropdown-wired TSL material graph editor for the selected object's material. Returns a `UIElement` ready for `sidebar.addTab('nodes', 'Nodes', panel)`. |
## Example
diff --git a/src/scene-studio/agent-tab.js b/src/scene-studio/agent-tab.js
new file mode 100644
index 000000000..05a082e4d
--- /dev/null
+++ b/src/scene-studio/agent-tab.js
@@ -0,0 +1,583 @@
+// Scene Studio: Agent tab.
+//
+// Sibling to the vendored r184 editor (never edits vendor/**): adds a chat
+// panel to the sidebar's tab row (Sidebar.addTab, see vendor/js/Sidebar.js)
+// that drives the open scene through tool calls instead of the mouse.
+//
+// The model only picks tools and arguments: every tool EXECUTES in this
+// module, as a real editor.execute(Command) the same File/Add menus use, so
+// Edit > Undo removes an agent action exactly like a manual one and autosave
+// (main.js) persists it. Generation tools reuse the diorama pipeline
+// (src/diorama/compose.js: composeWorld/forgeObject) that already backs the
+// Forge flow, and glTF import reuses the shared Draco/KTX2/Meshopt loader
+// (loader.js) the ?model= deep link and "Import from Forge" use.
+//
+// One reasoning round per turn is POSTed to /api/scene/agent (free, public,
+// rate-limited, built from the same provider chain + tool-calling building
+// blocks as the metered /api/v1/chat/completions client-tool lane, see that
+// file's header) and the loop re-posts with the tool results until the model
+// answers with no more tool calls or a per-turn round cap is hit.
+//
+// Every prompt that changes the scene pushes a version: a scene.toJSON()
+// snapshot plus a viewport screenshot, both captured synchronously right
+// after the mutating execute() calls (toDataURL must run in the same task as
+// the render, since the editor's renderer has no preserveDrawingBuffer;
+// Viewport.js renders synchronously inside each signal dispatch). The
+// version list lets the user step back to any earlier state: a MultiCmdsCommand
+// that removes the scene's current children and re-adds the snapshot's (plain
+// SetSceneCommand only APPENDS a parsed scene's children, since the vendored
+// Loader.js always runs it right after editor.clear(); that clear also wipes
+// undo history, which stepping back through versions must never do), so
+// restoring a version is itself one more undoable edit.
+
+import * as THREE from 'three';
+import { UIElement } from './vendor/js/libs/ui.js';
+import { AddObjectCommand } from './vendor/js/commands/AddObjectCommand.js';
+import { RemoveObjectCommand } from './vendor/js/commands/RemoveObjectCommand.js';
+import { SetPositionCommand } from './vendor/js/commands/SetPositionCommand.js';
+import { SetRotationCommand } from './vendor/js/commands/SetRotationCommand.js';
+import { SetScaleCommand } from './vendor/js/commands/SetScaleCommand.js';
+import { SetMaterialColorCommand } from './vendor/js/commands/SetMaterialColorCommand.js';
+import { MultiCmdsCommand } from './vendor/js/commands/MultiCmdsCommand.js';
+import { addGltfBufferToScene } from './loader.js';
+import { composeWorld, forgeObject } from '../diorama/compose.js';
+import { toastError } from '../shared/toast.js';
+
+const STYLE_ID = 'tws-studio-agent-styles';
+const ENDPOINT = '/api/scene/agent';
+const MAX_ROUNDS = 6; // tool-call round-trips per user turn, bounds a runaway loop on a free/rate-limited endpoint
+const MAX_VERSIONS = 30;
+
+function ensureStyles() {
+ if (typeof document === 'undefined' || document.getElementById(STYLE_ID)) return;
+ const el = document.createElement('style');
+ el.id = STYLE_ID;
+ el.textContent = CSS;
+ document.head.appendChild(el);
+}
+
+// ── Tool catalog ─────────────────────────────────────────────────────────
+// OpenAI-wire function tools (api/_lib/client-tool-round.js normalizes this
+// exact shape). Kept intentionally small and scene-scoped: the agent reads
+// and mutates the OPEN scene, it does not manage named server-side scenes
+// (that is packages/scene-mcp's job against /api/diorama, for an MCP client).
+const TOOLS = [
+ {
+ type: 'function',
+ function: {
+ name: 'list_objects',
+ description: "List every object currently in the scene: uuid, name, type, and position. Call this first to see what's there before moving, scaling, recoloring, or deleting anything.",
+ parameters: { type: 'object', properties: {} },
+ },
+ },
+ {
+ type: 'function',
+ function: {
+ name: 'add_object',
+ description: 'Generate one new 3D object from a short description and add it to the scene (e.g. "a red wooden chair"). Takes 10-60 seconds to forge a real mesh.',
+ parameters: {
+ type: 'object',
+ properties: { prompt: { type: 'string', description: 'A short description of the single object to generate.' } },
+ required: ['prompt'],
+ },
+ },
+ },
+ {
+ type: 'function',
+ function: {
+ name: 'build_world',
+ description: 'Generate a whole small scene (ground, several placed objects) from one sentence and add every object to the scene. Use for "build me a..." requests with multiple things; use add_object for a single item.',
+ parameters: {
+ type: 'object',
+ properties: { prompt: { type: 'string', description: 'A sentence describing the world to build.' } },
+ required: ['prompt'],
+ },
+ },
+ },
+ {
+ type: 'function',
+ function: {
+ name: 'move_object',
+ description: 'Move an object to an absolute position (scene units).',
+ parameters: {
+ type: 'object',
+ properties: {
+ uuid: { type: 'string' },
+ x: { type: 'number' }, y: { type: 'number' }, z: { type: 'number' },
+ },
+ required: ['uuid', 'x', 'y', 'z'],
+ },
+ },
+ },
+ {
+ type: 'function',
+ function: {
+ name: 'rotate_object',
+ description: 'Set an object\'s rotation, in degrees, around each axis.',
+ parameters: {
+ type: 'object',
+ properties: {
+ uuid: { type: 'string' },
+ x: { type: 'number' }, y: { type: 'number' }, z: { type: 'number' },
+ },
+ required: ['uuid', 'x', 'y', 'z'],
+ },
+ },
+ },
+ {
+ type: 'function',
+ function: {
+ name: 'scale_object',
+ description: 'Scale an object uniformly or per-axis (1 = original size).',
+ parameters: {
+ type: 'object',
+ properties: {
+ uuid: { type: 'string' },
+ x: { type: 'number' }, y: { type: 'number' }, z: { type: 'number' },
+ },
+ required: ['uuid', 'x', 'y', 'z'],
+ },
+ },
+ },
+ {
+ type: 'function',
+ function: {
+ name: 'set_material_color',
+ description: "Set an object's base material color.",
+ parameters: {
+ type: 'object',
+ properties: { uuid: { type: 'string' }, color: { type: 'string', description: 'CSS color, e.g. "#ff6a3d" or "tomato".' } },
+ required: ['uuid', 'color'],
+ },
+ },
+ },
+ {
+ type: 'function',
+ function: {
+ name: 'delete_object',
+ description: 'Remove an object from the scene.',
+ parameters: { type: 'object', properties: { uuid: { type: 'string' } }, required: ['uuid'] },
+ },
+ },
+];
+
+const SYSTEM_PROMPT = [
+ 'You are the Scene Studio agent on three.ws, a 3D scene editor. You help the visitor build and edit the 3D scene they have open by calling tools: every tool call is a real, undoable edit to their live scene.',
+ "Call list_objects before you move, scale, recolor, or delete anything you haven't just created, so you act on the right uuid.",
+ 'Use add_object for one new item, build_world for a whole small scene from a sentence. Both take real time to generate; say so briefly rather than going quiet.',
+ 'After acting, reply with a short, concrete sentence about what changed. Never claim to have done something you did not call a tool for.',
+ 'If a request is ambiguous (which object, what color), make the most reasonable choice yourself rather than asking a clarifying question. Only ask when truly nothing reasonable can be inferred.',
+].join(' ');
+
+function uid() {
+ return typeof crypto !== 'undefined' && crypto.randomUUID ? crypto.randomUUID() : `v-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+/** Synchronous screenshot right after a render, see module header on timing. */
+function captureScreenshot() {
+ try {
+ const canvas = document.querySelector('#viewport canvas');
+ if (!canvas) return null;
+ return canvas.toDataURL('image/jpeg', 0.72);
+ } catch {
+ return null; // tainted canvas (cross-origin texture) or no canvas yet, never fatal
+ }
+}
+
+function forceRender(editor) {
+ editor.signals.sceneGraphChanged.dispatch();
+}
+
+export class SceneAgent {
+ constructor(editor) {
+ this.editor = editor;
+ this.messages = [{ role: 'system', content: SYSTEM_PROMPT }];
+ this.versions = [];
+ }
+
+ objectSummary() {
+ const out = [];
+ this.editor.scene.traverse((obj) => {
+ if (obj === this.editor.scene) return;
+ out.push({
+ uuid: obj.uuid,
+ name: obj.name || obj.type,
+ type: obj.type,
+ position: { x: round(obj.position.x), y: round(obj.position.y), z: round(obj.position.z) },
+ });
+ });
+ return out;
+ }
+
+ findObject(uuidOrName) {
+ const byUuid = this.editor.objectByUuid(uuidOrName);
+ if (byUuid) return byUuid;
+ let found = null;
+ this.editor.scene.traverse((obj) => {
+ if (!found && obj.name === uuidOrName) found = obj;
+ });
+ return found;
+ }
+
+ async addGlbAsObject(glbUrl, label) {
+ const res = await fetch(glbUrl);
+ if (!res.ok) throw new Error(`HTTP ${res.status} fetching the generated model`);
+ const contents = await res.arrayBuffer();
+ return addGltfBufferToScene(this.editor, contents, label);
+ }
+
+ /** Executes one named tool call; returns the text that goes back to the model as the tool result. */
+ async runTool(name, rawArgs, { onStatus } = {}) {
+ let args;
+ try {
+ args = JSON.parse(rawArgs || '{}');
+ } catch {
+ return `Error: arguments were not valid JSON.`;
+ }
+
+ switch (name) {
+ case 'list_objects': {
+ const objects = this.objectSummary();
+ return objects.length ? JSON.stringify(objects) : 'The scene is empty.';
+ }
+
+ case 'add_object': {
+ const prompt = String(args.prompt || '').slice(0, 300);
+ if (!prompt) return 'Error: prompt is required.';
+ onStatus?.(`Forging "${prompt}"…`);
+ const object = { id: uid(), prompt, status: 'pending', glbUrl: null };
+ const result = await forgeObject(object);
+ if (result.status !== 'ready' || !result.glbUrl) return `Could not generate "${prompt}". Try a simpler description.`;
+ const added = await this.addGlbAsObject(result.glbUrl, prompt.slice(0, 48));
+ return `Added "${added.name || prompt}" (uuid ${added.uuid}) at position (${round(added.position.x)}, ${round(added.position.y)}, ${round(added.position.z)}).`;
+ }
+
+ case 'build_world': {
+ const prompt = String(args.prompt || '').slice(0, 400);
+ if (!prompt) return 'Error: prompt is required.';
+ onStatus?.(`Composing a scene for "${prompt}"…`);
+ let diorama;
+ try {
+ diorama = await composeWorld(prompt, {
+ onObject: (id, patch) => {
+ if (patch.status === 'forging') onStatus?.(`Forging piece ${id.slice(0, 6)}…`);
+ },
+ });
+ } catch (err) {
+ return `Could not compose that world: ${err.message}`;
+ }
+ const ready = diorama.objects.filter((o) => o.status === 'ready' && o.glbUrl);
+ if (!ready.length) return 'The world composed but no pieces forged successfully. Try a more concrete sentence.';
+ const added = [];
+ for (const obj of ready) {
+ try {
+ added.push(await this.addGlbAsObject(obj.glbUrl, obj.label || obj.prompt || 'Object'));
+ } catch {
+ // one failed import never sinks the rest of the world
+ }
+ }
+ return `Built the scene and added ${added.length} of ${diorama.objects.length} object(s): ${added.map((o) => o.name).join(', ') || 'none imported cleanly'}.`;
+ }
+
+ case 'move_object': {
+ const object = this.findObject(args.uuid);
+ if (!object) return `Error: no object with uuid "${args.uuid}".`;
+ this.editor.execute(new SetPositionCommand(this.editor, object, new THREE.Vector3(num(args.x), num(args.y), num(args.z))));
+ return `Moved ${object.name || object.uuid} to (${num(args.x)}, ${num(args.y)}, ${num(args.z)}).`;
+ }
+
+ case 'rotate_object': {
+ const object = this.findObject(args.uuid);
+ if (!object) return `Error: no object with uuid "${args.uuid}".`;
+ const rad = (d) => (num(d) * Math.PI) / 180;
+ this.editor.execute(new SetRotationCommand(this.editor, object, new THREE.Euler(rad(args.x), rad(args.y), rad(args.z))));
+ return `Rotated ${object.name || object.uuid} to (${num(args.x)}°, ${num(args.y)}°, ${num(args.z)}°).`;
+ }
+
+ case 'scale_object': {
+ const object = this.findObject(args.uuid);
+ if (!object) return `Error: no object with uuid "${args.uuid}".`;
+ this.editor.execute(new SetScaleCommand(this.editor, object, new THREE.Vector3(num(args.x, 1), num(args.y, 1), num(args.z, 1))));
+ return `Scaled ${object.name || object.uuid} to (${num(args.x, 1)}, ${num(args.y, 1)}, ${num(args.z, 1)}).`;
+ }
+
+ case 'set_material_color': {
+ const object = this.findObject(args.uuid);
+ if (!object) return `Error: no object with uuid "${args.uuid}".`;
+ const color = new THREE.Color();
+ try {
+ color.set(String(args.color || '#ffffff'));
+ } catch {
+ return `Error: "${args.color}" is not a color this editor understands.`;
+ }
+ this.editor.execute(new SetMaterialColorCommand(this.editor, object, 'color', color.getHex()));
+ return `Set ${object.name || object.uuid}'s color to ${args.color}.`;
+ }
+
+ case 'delete_object': {
+ const object = this.findObject(args.uuid);
+ if (!object) return `Error: no object with uuid "${args.uuid}".`;
+ const label = object.name || object.uuid;
+ this.editor.execute(new RemoveObjectCommand(this.editor, object));
+ return `Deleted ${label}.`;
+ }
+
+ default:
+ return `Error: unknown tool "${name}".`;
+ }
+ }
+
+ /** One user turn: loops tool rounds against /api/scene/agent until the model stops calling tools. */
+ async send(userText, { onStatus, onAssistant } = {}) {
+ this.messages.push({ role: 'user', content: userText });
+ let mutated = false;
+
+ for (let round = 0; round < MAX_ROUNDS; round++) {
+ let data;
+ try {
+ const res = await fetch(ENDPOINT, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ messages: this.messages, tools: TOOLS }),
+ });
+ data = await res.json().catch(() => ({}));
+ if (!res.ok) throw new Error(data?.error_description || data?.message || `HTTP ${res.status}`);
+ } catch (err) {
+ onAssistant?.(`Could not reach the scene agent: ${err.message}. Try again in a moment.`, { error: true });
+ return;
+ }
+
+ const toolCalls = Array.isArray(data.tool_calls) ? data.tool_calls : [];
+ if (data.content) onAssistant?.(data.content, {});
+ if (!toolCalls.length) {
+ this.messages.push({ role: 'assistant', content: data.content || '' });
+ break;
+ }
+
+ this.messages.push({
+ role: 'assistant',
+ content: data.content || null,
+ tool_calls: toolCalls.map((tc) => ({ id: tc.id, type: 'function', function: { name: tc.name, arguments: tc.arguments } })),
+ });
+
+ for (const call of toolCalls) {
+ onStatus?.(`${call.name.replace(/_/g, ' ')}…`);
+ let result;
+ try {
+ result = await this.runTool(call.name, call.arguments, { onStatus });
+ } catch (err) {
+ result = `Error running ${call.name}: ${err.message}`;
+ }
+ if (!/^Error:/.test(result) && call.name !== 'list_objects') mutated = true;
+ this.messages.push({ role: 'tool', tool_call_id: call.id, content: result });
+ }
+ }
+
+ onStatus?.(null);
+ if (mutated) this.pushVersion(userText);
+ }
+
+ pushVersion(label) {
+ forceRender(this.editor);
+ const snapshot = this.editor.scene.toJSON();
+ const screenshot = captureScreenshot();
+ this.versions.push({ id: uid(), label, at: Date.now(), snapshot, screenshot });
+ if (this.versions.length > MAX_VERSIONS) this.versions.shift();
+ return this.versions[this.versions.length - 1];
+ }
+
+ /**
+ * Restores a prior version as one more undoable edit. SetSceneCommand only
+ * APPENDS a parsed scene's children (vendor/js/Loader.js always calls it
+ * right after editor.clear(), which also wipes undo history); doing the
+ * same here would litter the current scene with the version's objects
+ * instead of replacing them. Composing explicit Remove + Add commands
+ * under one MultiCmdsCommand gets a real replace that stays undoable.
+ */
+ restoreVersion(versionId) {
+ const version = this.versions.find((v) => v.id === versionId);
+ if (!version) return false;
+ const loaded = new THREE.ObjectLoader().parse(version.snapshot);
+ const cmds = [];
+ for (const child of [...this.editor.scene.children]) {
+ cmds.push(new RemoveObjectCommand(this.editor, child));
+ }
+ while (loaded.children.length > 0) {
+ cmds.push(new AddObjectCommand(this.editor, loaded.children.pop()));
+ }
+ this.editor.execute(new MultiCmdsCommand(this.editor, cmds), `Restore "${version.label}"`);
+ return true;
+ }
+}
+
+function round(n) {
+ return Math.round(n * 100) / 100;
+}
+function num(v, fallback = 0) {
+ const n = Number(v);
+ return Number.isFinite(n) ? n : fallback;
+}
+
+/**
+ * Builds the Agent tab's panel and returns a UIElement ready for
+ * sidebar.addTab('agent', 'Agent', panel), see main.js wiring.
+ * @param {import('./vendor/js/Editor.js').Editor} editor
+ */
+export function createAgentPanel(editor) {
+ ensureStyles();
+ const agent = new SceneAgent(editor);
+
+ const root = document.createElement('div');
+ root.className = 'tws-agent-panel';
+ root.innerHTML = `
+ <p class="tws-agent-intro">Describe what you want in the scene. The agent reads it, makes real edits, and every change is undoable (Edit&nbsp;▸&nbsp;Undo).</p>
+ <div class="tws-agent-log" role="log" aria-live="polite"></div>
+ <p class="tws-agent-status" aria-live="polite" hidden></p>
+ <form class="tws-agent-form">
+ <textarea class="tws-agent-input" placeholder="e.g. add a red wooden chair by the window" rows="2" maxlength="500"></textarea>
+ <button type="submit" class="tws-agent-send">Send</button>
+ </form>
+ <div class="tws-agent-versions">
+ <h4>Versions</h4>
+ <p class="tws-agent-versions-empty">Changes the agent makes will show up here, step back to any of them.</p>
+ <ol class="tws-agent-versions-list"></ol>
+ </div>
+ `;
+
+ const log = root.querySelector('.tws-agent-log');
+ const statusEl = root.querySelector('.tws-agent-status');
+ const form = root.querySelector('.tws-agent-form');
+ const input = root.querySelector('.tws-agent-input');
+ const sendBtn = root.querySelector('.tws-agent-send');
+ const versionsList = root.querySelector('.tws-agent-versions-list');
+ const versionsEmpty = root.querySelector('.tws-agent-versions-empty');
+
+ function appendMessage(role, text) {
+ const row = document.createElement('div');
+ row.className = `tws-agent-msg tws-agent-msg-${role}`;
+ row.textContent = text;
+ log.appendChild(row);
+ log.scrollTop = log.scrollHeight;
+ }
+
+ function renderVersions() {
+ versionsList.innerHTML = '';
+ versionsEmpty.hidden = agent.versions.length > 0;
+ for (const version of agent.versions) {
+ const li = document.createElement('li');
+ li.className = 'tws-agent-version';
+ const time = new Date(version.at).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+ li.innerHTML = `
+ ${version.screenshot ? `<img src="${version.screenshot}" alt="" width="48" height="36" />` : '<span class="tws-agent-version-noimg" aria-hidden="true"></span>'}
+ <span class="tws-agent-version-label">${escapeHtml(version.label).slice(0, 60)}</span>
+ <span class="tws-agent-version-time">${time}</span>
+ <button type="button" data-restore="${version.id}">Restore</button>
+ `;
+ versionsList.appendChild(li);
+ }
+ }
+
+ versionsList.addEventListener('click', (e) => {
+ const btn = e.target.closest('[data-restore]');
+ if (!btn) return;
+ agent.restoreVersion(btn.dataset.restore);
+ appendMessage('agent', 'Restored that version.');
+ });
+
+ form.addEventListener('submit', async (e) => {
+ e.preventDefault();
+ const text = input.value.trim();
+ if (!text || sendBtn.disabled) return;
+ appendMessage('user', text);
+ input.value = '';
+ sendBtn.disabled = true;
+ input.disabled = true;
+
+ try {
+ await agent.send(text, {
+ onStatus: (text) => {
+ statusEl.hidden = !text;
+ if (text) statusEl.textContent = text;
+ },
+ onAssistant: (text, { error } = {}) => {
+ if (text) appendMessage(error ? 'error' : 'agent', text);
+ },
+ });
+ } catch (err) {
+ toastError(`Scene agent failed: ${err.message}`, { duration: 7000 });
+ } finally {
+ statusEl.hidden = true;
+ sendBtn.disabled = false;
+ input.disabled = false;
+ input.focus();
+ renderVersions();
+ }
+ });
+
+ input.addEventListener('keydown', (e) => {
+ if (e.key === 'Enter' && !e.shiftKey) {
+ e.preventDefault();
+ form.requestSubmit();
+ }
+ });
+
+ return new UIElement(root);
+}
+
+function escapeHtml(s) {
+ return String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+
+const CSS = `
+.tws-agent-panel {
+ display: flex; flex-direction: column; gap: 10px;
+ padding: 10px; font: 400 12.5px/1.45 system-ui, -apple-system, sans-serif;
+ color: var(--ink, #e8e8ec);
+ height: 100%; box-sizing: border-box;
+}
+.tws-agent-intro { margin: 0; color: #9a9aa8; font-size: 12px; }
+.tws-agent-log {
+ display: flex; flex-direction: column; gap: 6px;
+ min-height: 120px; max-height: 260px; overflow-y: auto;
+ border: 1px solid rgba(255,255,255,0.12); border-radius: 8px;
+ padding: 8px; background: rgba(0,0,0,0.2);
+}
+.tws-agent-msg { padding: 6px 9px; border-radius: 8px; max-width: 92%; white-space: pre-wrap; word-break: break-word; }
+.tws-agent-msg-user { align-self: flex-end; background: #2a6ef0; color: #fff; }
+.tws-agent-msg-agent { align-self: flex-start; background: rgba(255,255,255,0.08); }
+.tws-agent-msg-error { align-self: flex-start; background: rgba(255,90,90,0.18); color: #ffb3b3; }
+.tws-agent-status { margin: 0; color: #6ee7b7; font-size: 11.5px; font-style: italic; }
+.tws-agent-form { display: flex; gap: 6px; }
+.tws-agent-input {
+ flex: 1; resize: vertical; min-height: 36px;
+ border: 1px solid rgba(255,255,255,0.18); border-radius: 8px;
+ padding: 8px 9px; background: rgba(10,10,14,0.8); color: var(--ink, #e8e8ec);
+ font: inherit;
+}
+.tws-agent-input:focus-visible { outline: 2px solid #6ee7b7; outline-offset: 1px; }
+.tws-agent-send {
+ appearance: none; cursor: pointer; align-self: flex-end;
+ border: 0; border-radius: 8px; padding: 9px 14px;
+ background: #e8e8ec; color: #0a0a0f; font: 600 12.5px/1 system-ui, sans-serif;
+}
+.tws-agent-send:hover { background: #fff; }
+.tws-agent-send:disabled { opacity: 0.55; cursor: default; }
+.tws-agent-send:focus-visible { outline: 2px solid #6ee7b7; outline-offset: 2px; }
+.tws-agent-versions { border-top: 1px solid rgba(255,255,255,0.12); padding-top: 8px; }
+.tws-agent-versions h4 { margin: 0 0 6px; font-size: 11.5px; text-transform: uppercase; letter-spacing: 0.04em; color: #9a9aa8; }
+.tws-agent-versions-empty { margin: 0; color: #70707c; font-size: 11.5px; }
+.tws-agent-versions-list { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 4px; max-height: 180px; overflow-y: auto; }
+.tws-agent-version { display: flex; align-items: center; gap: 8px; padding: 4px; border-radius: 6px; }
+.tws-agent-version:hover { background: rgba(255,255,255,0.06); }
+.tws-agent-version img, .tws-agent-version-noimg { width: 48px; height: 36px; border-radius: 4px; object-fit: cover; background: #15151b; flex-shrink: 0; }
+.tws-agent-version-label { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 11.5px; }
+.tws-agent-version-time { color: #70707c; font-size: 10.5px; flex-shrink: 0; }
+.tws-agent-version button {
+ appearance: none; cursor: pointer; flex-shrink: 0;
+ border: 1px solid rgba(255,255,255,0.18); border-radius: 6px;
+ padding: 4px 8px; background: transparent; color: var(--ink, #e8e8ec);
+ font: 600 10.5px/1 system-ui, sans-serif;
+}
+.tws-agent-version button:hover { background: rgba(255,255,255,0.1); }
+.tws-agent-version button:focus-visible { outline: 2px solid #6ee7b7; outline-offset: 1px; }
+`;
diff --git a/src/scene-studio/main.js b/src/scene-studio/main.js
index bfac90d57..98f2aca3f 100644
--- a/src/scene-studio/main.js
+++ b/src/scene-studio/main.js
@@ -10,6 +10,14 @@ import './studio.css';
// theme, but the studio chrome (vendor css + studio.css) only ships dark.
document.documentElement.setAttribute('data-theme', 'dark');
+// Scene Studio is a full-screen app, the same category as a modal per
+// public/corner-stack.js's own doc comment ("a dialog that covers the screen
+// should add tws-modal-open to <body>"): without this the shared corner-stack
+// widgets (onboarding cards, the Walk Companion) float at a higher z-index
+// than the sidebar and can sit on top of its buttons, including the Agent
+// tab's version-restore controls.
+document.body.classList.add('tws-modal-open');
+
import * as THREE from 'three';
import { Editor } from './vendor/js/Editor.js';
@@ -30,6 +38,8 @@ import { TextGeometry } from 'three/addons/geometries/TextGeometry.js';
import { addGltfBufferToScene as sharedAddGltfBufferToScene } from './loader.js';
import { mountStudioActions } from './actions.js';
import { mountEmptyState } from './empty-state.js';
+import { createAgentPanel } from './agent-tab.js';
+import { createTslEditorPanel } from './tsl-editor.js';
import { enhanceAnimationA11y, enhanceToolbarA11y } from './toolbar-a11y.js';
import { toast, toastError } from '../shared/toast.js';
import { sanitizeRemoteScene } from './remote-scene.js';
@@ -61,6 +71,14 @@ container.appendChild(player.dom);
const sidebar = new Sidebar(editor);
container.appendChild(sidebar.dom);
+// Agent tab (drives the open scene through tool calls, see agent-tab.js) and
+// Nodes tab (TSL material graph editor, see tsl-editor.js), both sibling
+// additions to the vendored Scene/Project/Settings tabs, never touching
+// vendor/** (Sidebar.addTab is the vendored editor's own extension point).
+sidebar.addTab('agent', 'Agent', createAgentPanel(editor));
+sidebar.addTab('nodes', 'Nodes', createTslEditorPanel(editor));
+sidebar.select('scene'); // addTab() auto-selects the tab it just added; keep Scene the default
+
const menubar = new Menubar(editor);
container.appendChild(menubar.dom);
diff --git a/src/scene-studio/tsl-editor.js b/src/scene-studio/tsl-editor.js
new file mode 100644
index 000000000..688b4b82f
--- /dev/null
+++ b/src/scene-studio/tsl-editor.js
@@ -0,0 +1,447 @@
+// Scene Studio: Nodes tab, a TSL (Three.js Shading Language) material graph
+// editor for the selected object.
+//
+// Sibling to the vendored r184 editor (never edits vendor/**). The vendored
+// Project ▸ Renderer panel (Sidebar.Project.Renderer.js) already ships the
+// WebGL ↔ WebGPU toggle this needs (`new WebGPURenderer(...); await
+// renderer.init()`), so building a node material here needs no renderer work
+// of its own, it only needs a WebGPU (or node-material-capable WebGL)
+// renderer to actually light up, which the studio already has.
+//
+// The graph is dropdown-wired, not a freeform drag canvas: every node is a
+// card in a list, and every input on a card is a <select> of the other
+// nodes' labels. That is a deliberate, smaller scope than a node-link canvas
+// (no connection-rendering, no port hit-testing to get wrong) while staying a
+// real graph: nodes reference other nodes by id, cycles are rejected, and
+// the compiled result is a genuine three/tsl node tree, not a canned preset.
+//
+// "Apply to selected object" compiles the referenced output nodes into a
+// real THREE.MeshStandardNodeMaterial and swaps it onto the object via the
+// vendored SetMaterialCommand, so Edit ▸ Undo removes a bad graph exactly
+// like any other material edit.
+
+import {
+ Color, TextureLoader, SRGBColorSpace,
+ Scene, PerspectiveCamera, AmbientLight, DirectionalLight, Mesh, SphereGeometry, MeshStandardMaterial,
+} from 'three';
+import { UIElement } from './vendor/js/libs/ui.js';
+import { SetMaterialCommand } from './vendor/js/commands/SetMaterialCommand.js';
+import { toastError } from '../shared/toast.js';
+
+const STYLE_ID = 'tws-tsl-editor-styles';
+
+function ensureStyles() {
+ if (typeof document === 'undefined' || document.getElementById(STYLE_ID)) return;
+ const el = document.createElement('style');
+ el.id = STYLE_ID;
+ el.textContent = CSS;
+ document.head.appendChild(el);
+}
+
+// ── Node kind registry ──────────────────────────────────────────────────
+// `inputs`: named slots, each resolved to another node's compiled TSL value.
+// `params`: literal fields edited inline (not graph edges).
+// `build(tsl, resolvedInputs, params)` returns a compiled TSL node.
+const KINDS = {
+ uv: { label: 'UV', inputs: [], params: [], build: (tsl) => tsl.uv() },
+ time: { label: 'Time', inputs: [], params: [], build: (tsl) => tsl.time },
+ cameraPosition: { label: 'Camera position', inputs: [], params: [], build: (tsl) => tsl.cameraPosition },
+ normalWorld: { label: 'World normal', inputs: [], params: [], build: (tsl) => tsl.normalWorld },
+ float: {
+ label: 'Float', inputs: [],
+ params: [{ key: 'value', type: 'number', default: 1 }],
+ build: (tsl, _in, p) => tsl.float(num(p.value, 1)),
+ },
+ color: {
+ label: 'Color', inputs: [],
+ params: [{ key: 'hex', type: 'color', default: '#ffffff' }],
+ build: (tsl, _in, p) => tsl.color(new Color(p.hex || '#ffffff')),
+ },
+ vec3: {
+ label: 'Vector3', inputs: [],
+ params: [
+ { key: 'x', type: 'number', default: 0 }, { key: 'y', type: 'number', default: 0 }, { key: 'z', type: 'number', default: 0 },
+ ],
+ build: (tsl, _in, p) => tsl.vec3(num(p.x), num(p.y), num(p.z)),
+ },
+ texture: {
+ label: 'Texture', inputs: ['uv'],
+ params: [{ key: 'image', type: 'image', default: null }],
+ build: (tsl, inputs, p, ctx) => {
+ if (!p.image) throw new Error('Texture node needs an image.');
+ return tsl.texture(ctx.getTexture(p.image), inputs.uv ?? tsl.uv());
+ },
+ },
+ add: { label: 'Add', inputs: ['a', 'b'], params: [], build: (tsl, i) => req(i, 'a').add(req(i, 'b')) },
+ sub: { label: 'Subtract', inputs: ['a', 'b'], params: [], build: (tsl, i) => req(i, 'a').sub(req(i, 'b')) },
+ mul: { label: 'Multiply', inputs: ['a', 'b'], params: [], build: (tsl, i) => req(i, 'a').mul(req(i, 'b')) },
+ div: { label: 'Divide', inputs: ['a', 'b'], params: [], build: (tsl, i) => req(i, 'a').div(req(i, 'b')) },
+ mix: { label: 'Mix', inputs: ['a', 'b', 't'], params: [], build: (tsl, i) => tsl.mix(req(i, 'a'), req(i, 'b'), req(i, 't')) },
+ dot: { label: 'Dot', inputs: ['a', 'b'], params: [], build: (tsl, i) => tsl.dot(req(i, 'a'), req(i, 'b')) },
+ clamp: {
+ label: 'Clamp', inputs: ['a'],
+ params: [{ key: 'min', type: 'number', default: 0 }, { key: 'max', type: 'number', default: 1 }],
+ build: (tsl, i, p) => tsl.clamp(req(i, 'a'), num(p.min, 0), num(p.max, 1)),
+ },
+ oneMinus: { label: 'One minus', inputs: ['a'], params: [], build: (tsl, i) => tsl.oneMinus(req(i, 'a')) },
+ sin: { label: 'Sine', inputs: ['a'], params: [], build: (tsl, i) => tsl.sin(req(i, 'a')) },
+ pow: { label: 'Power', inputs: ['a'], params: [{ key: 'exponent', type: 'number', default: 2 }], build: (tsl, i, p) => tsl.pow(req(i, 'a'), num(p.exponent, 2)) },
+};
+
+const OUTPUT_SLOTS = [
+ { key: 'colorNode', label: 'Color' },
+ { key: 'emissiveNode', label: 'Emissive' },
+ { key: 'roughnessNode', label: 'Roughness' },
+ { key: 'metalnessNode', label: 'Metalness' },
+ { key: 'opacityNode', label: 'Opacity' },
+];
+
+function num(v, fallback = 0) {
+ const n = Number(v);
+ return Number.isFinite(n) ? n : fallback;
+}
+function req(inputs, slot) {
+ const v = inputs[slot];
+ if (v == null) throw new Error(`Missing input "${slot}".`);
+ return v;
+}
+function uid() {
+ return typeof crypto !== 'undefined' && crypto.randomUUID ? crypto.randomUUID() : `n-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+class GraphCompileError extends Error {}
+
+/** Topologically compiles `nodes` (a Map id -> node) for the given output node ids. Throws on a cycle or a missing input. */
+function compileGraph(tsl, ctx, nodes, outputIds) {
+ const resolved = new Map();
+ const visiting = new Set();
+
+ function resolve(id) {
+ if (resolved.has(id)) return resolved.get(id);
+ if (visiting.has(id)) throw new GraphCompileError('The graph has a cycle.');
+ const node = nodes.get(id);
+ if (!node) throw new GraphCompileError('A node references a deleted input.');
+ visiting.add(id);
+ const kind = KINDS[node.kind];
+ const inputs = {};
+ for (const slot of kind.inputs) {
+ if (node.inputs[slot]) inputs[slot] = resolve(node.inputs[slot]);
+ }
+ const value = kind.build(tsl, inputs, node.params, ctx);
+ visiting.delete(id);
+ resolved.set(id, value);
+ return value;
+ }
+
+ const out = {};
+ for (const id of outputIds) out[id] = resolve(id);
+ return out;
+}
+
+/**
+ * Builds the Nodes tab's panel: sidebar.addTab('nodes', 'Nodes', panel).
+ * @param {import('./vendor/js/Editor.js').Editor} editor
+ */
+export function createTslEditorPanel(editor) {
+ ensureStyles();
+
+ /** @type {Map<string, {id:string, kind:string, params:object, inputs:object}>} */
+ const nodes = new Map();
+ const outputs = { colorNode: null, emissiveNode: null, roughnessNode: null, metalnessNode: null, opacityNode: null };
+ const textureCache = new Map(); // dataURL -> THREE.Texture, so re-applying doesn't reload
+
+ const root = document.createElement('div');
+ root.className = 'tws-tsl-panel';
+ root.innerHTML = `
+ <p class="tws-tsl-intro">Build a material from nodes, wire each input by picking another node, then apply it to the selected object. Needs the WebGPU renderer (Project ▸ Renderer) to light up in the viewport.</p>
+ <div class="tws-tsl-preview"><canvas width="128" height="128"></canvas><p class="tws-tsl-preview-empty">Add nodes and apply to preview.</p></div>
+ <div class="tws-tsl-add">
+ <select class="tws-tsl-kind-select"></select>
+ <button type="button" class="tws-tsl-add-btn">+ Add node</button>
+ </div>
+ <ol class="tws-tsl-nodes"></ol>
+ <div class="tws-tsl-outputs"><h4>Material outputs</h4></div>
+ <button type="button" class="tws-tsl-apply">Apply to selected object</button>
+ <p class="tws-tsl-target"></p>
+ <p class="tws-tsl-error" role="alert" hidden></p>
+ `;
+
+ const kindSelect = root.querySelector('.tws-tsl-kind-select');
+ kindSelect.innerHTML = Object.entries(KINDS).map(([key, k]) => `<option value="${key}">${k.label}</option>`).join('');
+ const nodesList = root.querySelector('.tws-tsl-nodes');
+ const outputsBox = root.querySelector('.tws-tsl-outputs');
+ const applyBtn = root.querySelector('.tws-tsl-apply');
+ const targetEl = root.querySelector('.tws-tsl-target');
+ const errorEl = root.querySelector('.tws-tsl-error');
+ const previewCanvas = root.querySelector('.tws-tsl-preview canvas');
+ const previewEmpty = root.querySelector('.tws-tsl-preview-empty');
+
+ function showError(message) {
+ errorEl.textContent = message;
+ errorEl.hidden = !message;
+ }
+
+ function nodeLabel(node) {
+ return `${KINDS[node.kind].label} #${[...nodes.keys()].indexOf(node.id) + 1}`;
+ }
+
+ function inputOptionsHtml(selectedId, excludeId) {
+ const opts = ['<option value="">(none)</option>'];
+ for (const node of nodes.values()) {
+ if (node.id === excludeId) continue;
+ opts.push(`<option value="${node.id}" ${node.id === selectedId ? 'selected' : ''}>${nodeLabel(node)}</option>`);
+ }
+ return opts.join('');
+ }
+
+ function renderNodes() {
+ nodesList.innerHTML = '';
+ for (const node of nodes.values()) {
+ const kind = KINDS[node.kind];
+ const li = document.createElement('li');
+ li.className = 'tws-tsl-node';
+ li.dataset.id = node.id;
+ const paramsHtml = kind.params
+ .map((p) => {
+ if (p.type === 'color') return `<label>${p.key} <input type="color" data-param="${p.key}" value="${node.params[p.key]}"></label>`;
+ if (p.type === 'image') return `<label>${p.key} <input type="file" accept="image/*" data-param="${p.key}"></label>`;
+ return `<label>${p.key} <input type="number" step="any" data-param="${p.key}" value="${node.params[p.key]}"></label>`;
+ })
+ .join('');
+ const inputsHtml = kind.inputs
+ .map((slot) => `<label>${slot} <select data-input="${slot}">${inputOptionsHtml(node.inputs[slot], node.id)}</select></label>`)
+ .join('');
+ li.innerHTML = `
+ <div class="tws-tsl-node-head">
+ <strong>${nodeLabel(node)}</strong>
+ <button type="button" class="tws-tsl-node-remove" aria-label="Remove node">✕</button>
+ </div>
+ <div class="tws-tsl-node-body">${inputsHtml}${paramsHtml}</div>
+ `;
+ nodesList.appendChild(li);
+ }
+ }
+
+ function renderOutputs() {
+ outputsBox.querySelectorAll('.tws-tsl-output-row').forEach((el) => el.remove());
+ for (const slot of OUTPUT_SLOTS) {
+ const row = document.createElement('label');
+ row.className = 'tws-tsl-output-row';
+ row.innerHTML = `${slot.label} <select data-output="${slot.key}">${inputOptionsHtml(outputs[slot.key], null)}</select>`;
+ outputsBox.appendChild(row);
+ }
+ }
+
+ function syncTarget() {
+ const object = editor.selected;
+ targetEl.textContent = object ? `Applies to: ${object.name || object.type}` : 'Select an object in the scene first.';
+ applyBtn.disabled = !object;
+ }
+
+ nodesList.addEventListener('click', (e) => {
+ const removeBtn = e.target.closest('.tws-tsl-node-remove');
+ if (!removeBtn) return;
+ const id = removeBtn.closest('.tws-tsl-node').dataset.id;
+ nodes.delete(id);
+ for (const node of nodes.values()) {
+ for (const slot of Object.keys(node.inputs)) {
+ if (node.inputs[slot] === id) node.inputs[slot] = null;
+ }
+ }
+ for (const key of Object.keys(outputs)) if (outputs[key] === id) outputs[key] = null;
+ renderNodes();
+ renderOutputs();
+ });
+
+ nodesList.addEventListener('change', (e) => {
+ const li = e.target.closest('.tws-tsl-node');
+ if (!li) return;
+ const node = nodes.get(li.dataset.id);
+ if (!node) return;
+ if (e.target.dataset.input) {
+ node.inputs[e.target.dataset.input] = e.target.value || null;
+ } else if (e.target.dataset.param) {
+ const key = e.target.dataset.param;
+ if (e.target.type === 'file') {
+ const file = e.target.files?.[0];
+ if (!file) return;
+ const reader = new FileReader();
+ reader.onload = () => {
+ node.params[key] = reader.result;
+ };
+ reader.readAsDataURL(file);
+ } else {
+ node.params[key] = e.target.value;
+ }
+ }
+ });
+
+ outputsBox.addEventListener('change', (e) => {
+ if (!e.target.dataset.output) return;
+ outputs[e.target.dataset.output] = e.target.value || null;
+ });
+
+ root.querySelector('.tws-tsl-add-btn').addEventListener('click', () => {
+ const kind = kindSelect.value;
+ const def = KINDS[kind];
+ const node = {
+ id: uid(),
+ kind,
+ params: Object.fromEntries(def.params.map((p) => [p.key, p.default])),
+ inputs: Object.fromEntries(def.inputs.map((slot) => [slot, null])),
+ };
+ nodes.set(node.id, node);
+ renderNodes();
+ renderOutputs();
+ });
+
+ editor.signals.objectSelected.add(syncTarget);
+
+ async function loadTexture(dataUrl) {
+ if (textureCache.has(dataUrl)) return textureCache.get(dataUrl);
+ const texture = await new TextureLoader().loadAsync(dataUrl);
+ texture.colorSpace = SRGBColorSpace;
+ textureCache.set(dataUrl, texture);
+ return texture;
+ }
+
+ async function compileMaterial() {
+ const tsl = await import('three/tsl');
+ const outputIds = Object.values(outputs).filter(Boolean);
+ if (!outputIds.length) throw new Error('Wire at least one material output (Color, Emissive, ...) to a node.');
+ // build() runs synchronously (it is the recursive graph walk), so every
+ // image a texture node references must already be a loaded THREE.Texture
+ // in textureCache before compileGraph runs.
+ const images = [...nodes.values()].filter((n) => n.kind === 'texture' && n.params.image).map((n) => n.params.image);
+ await Promise.all([...new Set(images)].map((url) => loadTexture(url)));
+ const compiled = compileGraph(tsl, { getTexture: (url) => textureCache.get(url) }, nodes, outputIds);
+ const { MeshStandardNodeMaterial } = await import('three/webgpu');
+ const material = new MeshStandardNodeMaterial();
+ for (const slot of OUTPUT_SLOTS) {
+ if (outputs[slot.key]) material[slot.key] = compiled[outputs[slot.key]];
+ }
+ return material;
+ }
+
+ let previewHandle = null;
+ async function updatePreview() {
+ showError('');
+ let material;
+ try {
+ material = await compileMaterial();
+ } catch (err) {
+ previewEmpty.hidden = false;
+ previewEmpty.textContent = err instanceof GraphCompileError || err.message ? err.message : 'Could not compile this graph.';
+ if (previewHandle) previewHandle.stop();
+ return;
+ }
+ previewEmpty.hidden = true;
+ if (!previewHandle) previewHandle = await startPreview(previewCanvas);
+ previewHandle.setMaterial(material);
+ }
+
+ applyBtn.addEventListener('click', async () => {
+ const object = editor.selected;
+ if (!object) return;
+ applyBtn.disabled = true;
+ try {
+ const material = await compileMaterial();
+ material.name = `TSL graph (${object.name || object.type})`;
+ editor.execute(new SetMaterialCommand(editor, object, material, -1), 'Apply TSL material');
+ showError('');
+ } catch (err) {
+ showError(err.message || 'Could not apply this graph.');
+ toastError(`Could not apply the material graph: ${err.message}`, { duration: 7000 });
+ } finally {
+ applyBtn.disabled = !editor.selected;
+ }
+ });
+
+ nodesList.addEventListener('input', debounce(updatePreview, 400));
+ outputsBox.addEventListener('change', debounce(updatePreview, 50));
+
+ syncTarget();
+ renderOutputs();
+
+ return new UIElement(root);
+}
+
+function debounce(fn, ms) {
+ let t;
+ return (...args) => {
+ clearTimeout(t);
+ t = setTimeout(() => fn(...args), ms);
+ };
+}
+
+/** A small self-contained WebGPU preview: one lit sphere wearing the live-compiled material. */
+async function startPreview(canvas) {
+ const { WebGPURenderer } = await import('three/webgpu');
+ const renderer = new WebGPURenderer({ canvas, antialias: true });
+ await renderer.init();
+ renderer.setSize(canvas.width, canvas.height, false);
+
+ const scene = new Scene();
+ const camera = new PerspectiveCamera(45, 1, 0.1, 10);
+ camera.position.set(0, 0, 2.4);
+ scene.add(new AmbientLight(0xffffff, 0.6));
+ const dirLight = new DirectionalLight(0xffffff, 2.2);
+ dirLight.position.set(2, 3, 4);
+ scene.add(dirLight);
+
+ const mesh = new Mesh(new SphereGeometry(0.85, 48, 48), new MeshStandardMaterial());
+ scene.add(mesh);
+
+ let stopped = false;
+ function animate() {
+ if (stopped) return;
+ mesh.rotation.y += 0.012;
+ renderer.render(scene, camera);
+ requestAnimationFrame(animate);
+ }
+ animate();
+
+ return {
+ setMaterial(material) {
+ mesh.material.dispose();
+ mesh.material = material;
+ },
+ stop() {
+ stopped = true;
+ },
+ };
+}
+
+const CSS = `
+.tws-tsl-panel { display: flex; flex-direction: column; gap: 10px; padding: 10px; font: 400 12.5px/1.45 system-ui, -apple-system, sans-serif; color: var(--ink, #e8e8ec); }
+.tws-tsl-intro { margin: 0; color: #9a9aa8; font-size: 12px; }
+.tws-tsl-preview { position: relative; width: 128px; height: 128px; border-radius: 8px; overflow: hidden; background: #0d0d12; border: 1px solid rgba(255,255,255,0.12); align-self: center; }
+.tws-tsl-preview canvas { width: 100%; height: 100%; display: block; }
+.tws-tsl-preview-empty { position: absolute; inset: 0; display: flex; align-items: center; justify-content: center; text-align: center; margin: 0; padding: 8px; font-size: 10.5px; color: #70707c; background: rgba(13,13,18,0.9); }
+.tws-tsl-add { display: flex; gap: 6px; }
+.tws-tsl-kind-select, .tws-tsl-node select, .tws-tsl-node input, .tws-tsl-output-row select {
+ border: 1px solid rgba(255,255,255,0.18); border-radius: 6px; background: rgba(10,10,14,0.8); color: var(--ink, #e8e8ec);
+ padding: 5px 6px; font: inherit; font-size: 11.5px;
+}
+.tws-tsl-add-btn, .tws-tsl-apply, .tws-tsl-node-remove {
+ appearance: none; cursor: pointer; border: 1px solid rgba(255,255,255,0.18); border-radius: 6px;
+ background: transparent; color: var(--ink, #e8e8ec); font: 600 11.5px/1 system-ui, sans-serif; padding: 6px 10px;
+}
+.tws-tsl-add-btn:hover, .tws-tsl-node-remove:hover { background: rgba(255,255,255,0.08); }
+.tws-tsl-apply { background: #e8e8ec; color: #0a0a0f; align-self: flex-start; }
+.tws-tsl-apply:hover { background: #fff; }
+.tws-tsl-apply:disabled { opacity: 0.5; cursor: default; }
+.tws-tsl-apply:focus-visible, .tws-tsl-add-btn:focus-visible, .tws-tsl-node-remove:focus-visible { outline: 2px solid #6ee7b7; outline-offset: 2px; }
+.tws-tsl-nodes { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 6px; max-height: 280px; overflow-y: auto; }
+.tws-tsl-node { border: 1px solid rgba(255,255,255,0.12); border-radius: 8px; padding: 8px; background: rgba(255,255,255,0.03); }
+.tws-tsl-node-head { display: flex; align-items: center; justify-content: space-between; margin-bottom: 6px; }
+.tws-tsl-node-head .tws-tsl-node-remove { padding: 2px 6px; }
+.tws-tsl-node-body { display: flex; flex-wrap: wrap; gap: 8px; }
+.tws-tsl-node-body label { display: flex; flex-direction: column; gap: 3px; font-size: 10.5px; color: #9a9aa8; }
+.tws-tsl-outputs { border-top: 1px solid rgba(255,255,255,0.12); padding-top: 8px; display: flex; flex-direction: column; gap: 6px; }
+.tws-tsl-outputs h4 { margin: 0; font-size: 11.5px; text-transform: uppercase; letter-spacing: 0.04em; color: #9a9aa8; }
+.tws-tsl-output-row { display: flex; align-items: center; justify-content: space-between; gap: 8px; font-size: 12px; }
+.tws-tsl-target { margin: 0; font-size: 11.5px; color: #9a9aa8; }
+.tws-tsl-error { margin: 0; font-size: 11.5px; color: #ff7a8a; }
+.tws-tsl-error[hidden] { display: none; }
+`;
diff --git a/tests/scene-studio-agent-restore.test.js b/tests/scene-studio-agent-restore.test.js
new file mode 100644
index 000000000..054f437b3
--- /dev/null
+++ b/tests/scene-studio-agent-restore.test.js
@@ -0,0 +1,111 @@
+/**
+ * Scene Studio Agent tab: SceneAgent.restoreVersion regression test.
+ *
+ * restoreVersion used to execute a plain SetSceneCommand to step back to an
+ * earlier version. SetSceneCommand's constructor only ever pushes
+ * AddObjectCommands for the loaded scene's children; it never removes the
+ * current scene's children, because its one vendor call site
+ * (vendor/js/Loader.js, "import as scene") always runs right after
+ * editor.clear(). Reusing it here left the version's objects stacked on top
+ * of whatever was already in the scene instead of replacing it, so
+ * "restore an earlier version" silently duplicated objects and never
+ * actually went back. The fix composes explicit Remove + Add commands under
+ * one MultiCmdsCommand instead.
+ *
+ * These tests build a real vendored Editor (the same class main.js
+ * constructs), stubbing only the two browser globals the vendor code reads
+ * at construction time: `window` (Storage falls back to a no-op stub when
+ * `window.indexedDB` is undefined) and `navigator.language` (Config's
+ * startup default), plus the `signals` pub/sub library main.js normally
+ * gets from the classic `<script>` tag in pages/scene.html.
+ */
+import { describe, expect, it } from 'vitest';
+
+class StubSignal {
+ constructor() {
+ this._listeners = [];
+ this.active = true;
+ }
+ add(fn) {
+ this._listeners.push(fn);
+ }
+ dispatch(...args) {
+ if (!this.active) return;
+ for (const fn of this._listeners) fn(...args);
+ }
+}
+
+globalThis.window ??= {};
+// Config.js reads/writes window.localStorage[name] as a plain property, not
+// through getItem/setItem, so a bare object stands in for it.
+globalThis.window.localStorage ??= {};
+globalThis.navigator ??= { language: 'en-US' };
+globalThis.signals = { Signal: StubSignal };
+// Editor.js's module-level `save()` helper (File > Export, unused by these
+// tests) creates an <a> at import time; give it an inert stand-in.
+globalThis.document ??= { createElement: () => ({ style: {}, setAttribute() {}, click() {} }) };
+
+const { Editor } = await import('../src/scene-studio/vendor/js/Editor.js');
+const { AddObjectCommand } = await import('../src/scene-studio/vendor/js/commands/AddObjectCommand.js');
+const { SetMaterialColorCommand } = await import('../src/scene-studio/vendor/js/commands/SetMaterialColorCommand.js');
+const { SceneAgent } = await import('../src/scene-studio/agent-tab.js');
+const THREE = await import('three');
+
+function addBox(editor, name, colorHex) {
+ const mesh = new THREE.Mesh(
+ new THREE.BoxGeometry(1, 1, 1),
+ new THREE.MeshStandardMaterial({ color: colorHex }),
+ );
+ mesh.name = name;
+ editor.execute(new AddObjectCommand(editor, mesh));
+ return mesh;
+}
+
+describe('SceneAgent.restoreVersion', () => {
+ it('replaces the scene with the snapshot instead of appending to it', () => {
+ const editor = new Editor();
+ const agent = new SceneAgent(editor);
+
+ const redBox = addBox(editor, 'RedBox', 0xff0000);
+ const v1 = agent.pushVersion('add red box');
+
+ editor.execute(new SetMaterialColorCommand(editor, redBox, 'color', 0x00ff00));
+ agent.pushVersion('recolor to green');
+ expect(editor.scene.children).toHaveLength(1);
+ expect(redBox.material.color.getHex()).toBe(0x00ff00);
+
+ const restored = agent.restoreVersion(v1.id);
+
+ expect(restored).toBe(true);
+ expect(editor.scene.children).toHaveLength(1);
+ expect(editor.scene.children[0].material.color.getHex()).toBe(0xff0000);
+ });
+
+ it('restoring a version is itself one more undoable edit', () => {
+ const editor = new Editor();
+ const agent = new SceneAgent(editor);
+
+ addBox(editor, 'RedBox', 0xff0000);
+ const v1 = agent.pushVersion('add red box');
+
+ addBox(editor, 'BlueBox', 0x0000ff);
+ agent.pushVersion('add blue box');
+ expect(editor.scene.children).toHaveLength(2);
+
+ agent.restoreVersion(v1.id);
+ expect(editor.scene.children).toHaveLength(1);
+
+ editor.undo();
+ expect(editor.scene.children).toHaveLength(2);
+ });
+
+ it('returns false for an unknown version id and leaves the scene untouched', () => {
+ const editor = new Editor();
+ const agent = new SceneAgent(editor);
+ addBox(editor, 'RedBox', 0xff0000);
+ agent.pushVersion('add red box');
+
+ expect(agent.restoreVersion('not-a-real-id')).toBe(false);
+ expect(editor.scene.children).toHaveLength(1);
+ });
+});