feat(threejs): add visibility optimization, host styling, transparent background

- Add visibility-based animation pause (IntersectionObserver + wrapped rAF)
- Zero CPU usage when widget scrolls out of view
- Apply host style variables via useHostStyles
- Support transparent WebGL background (alpha: true)
- Use light-dark() for theme-aware fallback colors
- Tool no longer echoes code back in result
- Document performance features in README

Author: antonpk1

examples/threejs-server/README.md

@@ -108,3 +108,27 @@ React component that:
 - Displays streaming preview from `toolInputsPartial.code` as code arrives
 - Executes final code from `toolInputs.code` when complete
 - Renders to a pre-created canvas with configurable height
+
+## Performance
+
+### Visibility-Based Pause
+
+Animation automatically pauses when the widget scrolls out of view:
+
+- Uses `IntersectionObserver` to track visibility (browser-native, no polling)
+- Wraps `requestAnimationFrame` to skip frames when not visible
+- Animation loop stops completely → zero CPU usage while hidden
+- Queued callbacks resume instantly when scrolled back into view
+
+This is transparent to user code - just use `requestAnimationFrame` normally.
+
+### Transparent Background
+
+Supports alpha transparency for seamless host UI integration:
+
+```javascript
+const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true });
+renderer.setClearColor(0x000000, 0); // Fully transparent
+```
+
+This is the default - 3D objects composite directly over the host background.

examples/threejs-server/server.ts

@@ -22,9 +22,9 @@ const DIST_DIR = import.meta.filename.endsWith(".ts")
 // Default code example for the Three.js widget
 const DEFAULT_THREEJS_CODE = `const scene = new THREE.Scene();
 const camera = new THREE.PerspectiveCamera(75, width / height, 0.1, 1000);
-const renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
+const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true });
 renderer.setSize(width, height);
-renderer.setClearColor(0x1a1a2e);
+renderer.setClearColor(0x000000, 0); // Transparent background
 
 const cube = new THREE.Mesh(
   new THREE.BoxGeometry(1, 1, 1),
@@ -54,35 +54,38 @@ const THREEJS_DOCUMENTATION = `# Three.js Widget Documentation
 - \`OrbitControls\` - Interactive camera controls
 - \`EffectComposer\`, \`RenderPass\`, \`UnrealBloomPass\` - Post-processing effects
 
-## Basic Template
+## Basic Template (Transparent Background)
 \`\`\`javascript
 const scene = new THREE.Scene();
 const camera = new THREE.PerspectiveCamera(75, width / height, 0.1, 1000);
-const renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
+const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true });
 renderer.setSize(width, height);
-renderer.setClearColor(0x1a1a2e);  // Dark background
+renderer.setClearColor(0x000000, 0); // Transparent - blends with host UI
 
 // Add objects here...
 
 camera.position.z = 5;
-renderer.render(scene, camera);  // Static render
+renderer.render(scene, camera);
 \`\`\`
 
-## Example: Rotating Cube with Lighting
+## Transparent vs Solid Background
+- **Transparent (default)**: Use \`alpha: true\` and \`setClearColor(0x000000, 0)\`
+- **Solid color**: Use \`setClearColor(0x1a1a2e)\` (omit alpha param)
+
+## Example: Rotating Cube
 \`\`\`javascript
 const scene = new THREE.Scene();
 const camera = new THREE.PerspectiveCamera(75, width / height, 0.1, 1000);
-const renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
+const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true });
 renderer.setSize(width, height);
-renderer.setClearColor(0x1a1a2e);
+renderer.setClearColor(0x000000, 0);
 
 const cube = new THREE.Mesh(
   new THREE.BoxGeometry(1, 1, 1),
   new THREE.MeshStandardMaterial({ color: 0x00ff88 })
 );
 scene.add(cube);
 
-// Lighting - keep intensity at 1 or below
 scene.add(new THREE.DirectionalLight(0xffffff, 1));
 scene.add(new THREE.AmbientLight(0x404040));
 
@@ -101,9 +104,9 @@ animate();
 \`\`\`javascript
 const scene = new THREE.Scene();
 const camera = new THREE.PerspectiveCamera(75, width / height, 0.1, 1000);
-const renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
+const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true });
 renderer.setSize(width, height);
-renderer.setClearColor(0x2d2d44);
+renderer.setClearColor(0x000000, 0);
 
 const controls = new OrbitControls(camera, renderer.domElement);
 controls.enableDamping = true;
@@ -128,7 +131,7 @@ animate();
 \`\`\`
 
 ## Tips
-- Always set \`renderer.setClearColor()\` to a dark color
+- Use \`alpha: true\` for transparent backgrounds that blend with host UI
 - Keep light intensity ≤ 1 to avoid washed-out scenes
 - Use \`MeshStandardMaterial\` for realistic lighting
 - For animations, use \`requestAnimationFrame\`
@@ -157,7 +160,7 @@ export function createServer(): McpServer {
     {
       title: "Show Three.js Scene",
       description:
-        "Render an interactive 3D scene with custom Three.js code. Available globals: THREE, OrbitControls, EffectComposer, RenderPass, UnrealBloomPass, canvas, width, height.",
+        "Render an interactive 3D scene with custom Three.js code. Supports transparent backgrounds (alpha: true) for seamless host UI integration. Available globals: THREE, OrbitControls, EffectComposer, RenderPass, UnrealBloomPass, canvas, width, height.",
       inputSchema: {
         code: z
           .string()
@@ -171,16 +174,14 @@ export function createServer(): McpServer {
           .describe("Height in pixels"),
       },
       outputSchema: z.object({
-        code: z.string(),
-        height: z.number(),
+        success: z.boolean(),
       }),
       _meta: { ui: { resourceUri } },
     },
-    async ({ code, height }) => {
-      const data = { code, height };
+    async () => {
       return {
-        content: [{ type: "text", text: JSON.stringify(data) }],
-        structuredContent: data,
+        content: [{ type: "text", text: "Three.js scene rendered" }],
+        structuredContent: { success: true },
       };
     },
   );

examples/threejs-server/src/global.css

@@ -1,27 +1,31 @@
+:root {
+  color-scheme: light dark;
+}
+
 * {
   box-sizing: border-box;
 }
 
 html, body {
-  font-family: system-ui, -apple-system, sans-serif;
+  font-family: var(--font-sans, system-ui, -apple-system, sans-serif);
   font-size: 1rem;
   margin: 0;
   padding: 0;
-  background: #1a1a2e;
+  background: transparent;
 }
 
 .loading {
   display: flex;
   align-items: center;
   justify-content: center;
   height: 400px;
-  color: #888;
+  color: var(--color-text-secondary, #888);
   font-size: 14px;
 }
 
 .error {
   padding: 20px;
-  color: #ff6b6b;
+  color: var(--color-text-danger, #ff6b6b);
 }
 
 .threejs-container {
@@ -35,9 +39,9 @@ html, body {
   display: flex;
   align-items: center;
   justify-content: center;
-  color: #ff6b6b;
-  background: rgba(26, 26, 46, 0.9);
-  border-radius: 8px;
-  font-family: system-ui;
+  color: var(--color-text-danger, #ff6b6b);
+  background: var(--color-background-secondary, rgba(26, 26, 46, 0.9));
+  border-radius: var(--border-radius-md, 8px);
+  font-family: var(--font-sans, system-ui);
   padding: 20px;
 }

examples/threejs-server/src/mcp-app-wrapper.tsx

@@ -5,7 +5,7 @@
  * props to the actual widget component.
  */
 import type { App, McpUiHostContext } from "@modelcontextprotocol/ext-apps";
-import { useApp } from "@modelcontextprotocol/ext-apps/react";
+import { useApp, useHostStyles } from "@modelcontextprotocol/ext-apps/react";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { StrictMode, useState, useCallback, useEffect } from "react";
 import { createRoot } from "react-dom/client";
@@ -78,6 +78,9 @@ function McpAppWrapper() {
     },
   });
 
+  // Apply host styling (theme, CSS variables, fonts)
+  useHostStyles(app);
+
   // Get initial host context after connection
   useEffect(() => {
     if (app) {