sceneview-mcp 3.4.6 → 3.4.8

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Thomas Gorisse
+Copyright (c) 2024-2026 Thomas Gorisse
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -3,9 +3,11 @@
 [![npm version](https://img.shields.io/npm/v/sceneview-mcp?color=6c35aa)](https://www.npmjs.com/package/sceneview-mcp)
 [![npm downloads](https://img.shields.io/npm/dm/sceneview-mcp?color=blue)](https://www.npmjs.com/package/sceneview-mcp)
 [![MCP](https://img.shields.io/badge/MCP-v1.12-blue)](https://modelcontextprotocol.io/)
-[![License](https://img.shields.io/badge/License-Apache%202.0-green)](https://www.apache.org/licenses/LICENSE-2.0)
+[![License](https://img.shields.io/badge/License-MIT-green)](./LICENSE)
 [![Node](https://img.shields.io/badge/Node-%3E%3D18-brightgreen)](https://nodejs.org/)
 
+> **Disclaimer:** This tool generates code suggestions for the SceneView SDK. Generated code is provided "as is" without warranty. Always review generated code before use in production. This is not a substitute for professional software engineering review. See [TERMS.md](./TERMS.md) and [PRIVACY.md](./PRIVACY.md).
+
 The official [Model Context Protocol](https://modelcontextprotocol.io/) server for **SceneView** — giving AI assistants deep knowledge of the SceneView 3D/AR SDK so they generate correct, compilable Kotlin code.
 
 ---
@@ -265,6 +267,12 @@ Published to npm on each SceneView release:
 npm publish --access public
 ```
 
+## Legal
+
+- [LICENSE](./LICENSE) — MIT License
+- [TERMS.md](./TERMS.md) — Terms of Service
+- [PRIVACY.md](./PRIVACY.md) — Privacy Policy (no data collected)
+
 ## License
 
-Apache 2.0 — same as SceneView.
+MIT — see [LICENSE](./LICENSE).

package/dist/index.js

@@ -11,7 +11,19 @@ import { MIGRATION_GUIDE } from "./migration.js";
 import { fetchKnownIssues } from "./issues.js";
 import { parseNodeSections, findNodeSection, listNodeTypes } from "./node-reference.js";
 import { PLATFORM_ROADMAP, BEST_PRACTICES, AR_SETUP_GUIDE, TROUBLESHOOTING_GUIDE } from "./guides.js";
+import { buildPreviewUrl, validatePreviewInput, formatPreviewResponse } from "./preview.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
+// ─── Legal disclaimer ─────────────────────────────────────────────────────────
+const DISCLAIMER = '\n\n---\n*Generated code suggestion. Review before use in production. See [TERMS.md](https://github.com/SceneView/sceneview/blob/main/mcp/TERMS.md).*';
+function withDisclaimer(content) {
+    if (content.length === 0)
+        return content;
+    const last = content[content.length - 1];
+    return [
+        ...content.slice(0, -1),
+        { ...last, text: last.text + DISCLAIMER },
+    ];
+}
 let API_DOCS;
 try {
     API_DOCS = readFileSync(resolve(__dirname, "../llms.txt"), "utf-8");
@@ -205,24 +217,32 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "render_3d_preview",
-            description: "Generates an interactive 3D preview link for a glTF/GLB model. Returns a URL to sceneview.github.io/preview that renders the model in the browser with orbit controls, AR support, and sharing. Use this when you want to show a 3D model to the user — paste the link in your response and they can click to see it live. Also works with any publicly accessible .glb URL.",
+            description: "Generates an interactive 3D preview link. Accepts a model URL, a SceneView code snippet, or both. Returns a URL to sceneview.github.io/preview that renders the model in the browser with orbit controls, AR support, and sharing. For model URLs: embeds a model-viewer link directly. For code snippets: shows the 3D preview with the code in a companion panel. Use this when you want to show a 3D model to the user — paste the link in your response and they can click to see it live.",
             inputSchema: {
                 type: "object",
                 properties: {
                     modelUrl: {
                         type: "string",
-                        description: "Public URL to a .glb or .gltf model file. Must be HTTPS and CORS-enabled.",
+                        description: "Public URL to a .glb or .gltf model file. Must be HTTPS and CORS-enabled. If omitted, a default model is used.",
+                    },
+                    codeSnippet: {
+                        type: "string",
+                        description: "SceneView code snippet (Kotlin or Swift) to display alongside the 3D preview in a companion panel. Useful when showing generated code together with a live preview.",
                     },
                     autoRotate: {
                         type: "boolean",
-                        description: "Auto-rotate the model (default: true)",
+                        description: "Auto-rotate the model (default: true).",
                     },
                     ar: {
                         type: "boolean",
-                        description: "Enable AR mode on supported devices (default: true)",
+                        description: "Enable AR mode on supported devices (default: true).",
+                    },
+                    title: {
+                        type: "string",
+                        description: "Custom title shown above the preview.",
                     },
                 },
-                required: ["modelUrl"],
+                required: [],
             },
         },
     ],
@@ -262,7 +282,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const codeLang = isIos ? "swift" : "kotlin";
             const codeLabel = isIos ? "**Swift (SwiftUI):**" : "**Kotlin (Jetpack Compose):**";
             return {
-                content: [
+                content: withDisclaimer([
                     {
                         type: "text",
                         text: [
@@ -281,7 +301,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             `> ${sample.prompt}`,
                         ].join("\n"),
                     },
-                ],
+                ]),
             };
         }
         // ── list_samples ──────────────────────────────────────────────────────────
@@ -307,14 +327,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return `### \`${s.id}\`\n**${s.title}**${s.language === "swift" ? " (Swift/iOS)" : ""}\n${s.description}\n*Tags:* ${s.tags.join(", ")}\n${depLabel} \`${s.dependency}\`\n\nCall \`get_sample("${s.id}")\` for the full code.`;
             })
                 .join("\n\n---\n\n");
-            return { content: [{ type: "text", text: header + rows }] };
+            return { content: withDisclaimer([{ type: "text", text: header + rows }]) };
         }
         // ── get_setup ─────────────────────────────────────────────────────────────
         case "get_setup": {
             const type = request.params.arguments?.type;
             if (type === "3d") {
                 return {
-                    content: [
+                    content: withDisclaimer([
                         {
                             type: "text",
                             text: [
@@ -330,12 +350,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 `No manifest changes required for 3D-only scenes.`,
                             ].join("\n"),
                         },
-                    ],
+                    ]),
                 };
             }
             if (type === "ar") {
                 return {
-                    content: [
+                    content: withDisclaimer([
                         {
                             type: "text",
                             text: [
@@ -358,7 +378,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 `\`\`\``,
                             ].join("\n"),
                         },
-                    ],
+                    ]),
                 };
             }
             return {
@@ -377,11 +397,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             const issues = validateCode(code);
             const report = formatValidationReport(issues);
-            return { content: [{ type: "text", text: report }] };
+            return { content: withDisclaimer([{ type: "text", text: report }]) };
         }
         // ── get_migration_guide ───────────────────────────────────────────────────
         case "get_migration_guide": {
-            return { content: [{ type: "text", text: MIGRATION_GUIDE }] };
+            return { content: withDisclaimer([{ type: "text", text: MIGRATION_GUIDE }]) };
         }
         // ── get_node_reference ────────────────────────────────────────────────────
         case "get_node_reference": {
@@ -410,7 +430,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
             return {
-                content: [
+                content: withDisclaimer([
                     {
                         type: "text",
                         text: [
@@ -419,33 +439,33 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             section.content,
                         ].join("\n"),
                     },
-                ],
+                ]),
             };
         }
         // ── get_platform_roadmap ────────────────────────────────────────────────
         case "get_platform_roadmap": {
-            return { content: [{ type: "text", text: PLATFORM_ROADMAP }] };
+            return { content: withDisclaimer([{ type: "text", text: PLATFORM_ROADMAP }]) };
         }
         // ── get_best_practices ───────────────────────────────────────────────────
         case "get_best_practices": {
             const category = request.params.arguments?.category || "all";
             const text = BEST_PRACTICES[category] ?? BEST_PRACTICES["all"];
-            return { content: [{ type: "text", text }] };
+            return { content: withDisclaimer([{ type: "text", text }]) };
         }
         // ── get_ar_setup ─────────────────────────────────────────────────────────
         case "get_ar_setup": {
-            return { content: [{ type: "text", text: AR_SETUP_GUIDE }] };
+            return { content: withDisclaimer([{ type: "text", text: AR_SETUP_GUIDE }]) };
         }
         // ── get_troubleshooting ──────────────────────────────────────────────────
         case "get_troubleshooting": {
-            return { content: [{ type: "text", text: TROUBLESHOOTING_GUIDE }] };
+            return { content: withDisclaimer([{ type: "text", text: TROUBLESHOOTING_GUIDE }]) };
         }
         // ── get_ios_setup ─────────────────────────────────────────────────────────
         case "get_ios_setup": {
             const iosType = request.params.arguments?.type;
             if (iosType === "3d") {
                 return {
-                    content: [
+                    content: withDisclaimer([
                         {
                             type: "text",
                             text: [
@@ -525,12 +545,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 `No manifest or permission changes needed for 3D-only scenes.`,
                             ].join("\n"),
                         },
-                    ],
+                    ]),
                 };
             }
             if (iosType === "ar") {
                 return {
-                    content: [
+                    content: withDisclaimer([
                         {
                             type: "text",
                             text: [
@@ -616,7 +636,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 `\`\`\``,
                             ].join("\n"),
                         },
-                    ],
+                    ]),
                 };
             }
             return {
@@ -627,7 +647,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         // ── get_web_setup ────────────────────────────────────────────────────────
         case "get_web_setup": {
             return {
-                content: [
+                content: withDisclaimer([
                     {
                         type: "text",
                         text: [
@@ -712,47 +732,26 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             `- glTF/GLB format only (same as Android)`,
                         ].join("\n"),
                     },
-                ],
+                ]),
             };
         }
         // ── render_3d_preview ──────────────────────────────────────────────────
         case "render_3d_preview": {
             const modelUrl = request.params.arguments?.modelUrl;
-            const autoRotate = request.params.arguments?.autoRotate ?? true;
-            const ar = request.params.arguments?.ar ?? true;
-            if (!modelUrl) {
+            const codeSnippet = request.params.arguments?.codeSnippet;
+            const autoRotate = request.params.arguments?.autoRotate;
+            const ar = request.params.arguments?.ar;
+            const title = request.params.arguments?.title;
+            const validationError = validatePreviewInput(modelUrl, codeSnippet);
+            if (validationError) {
                 return {
-                    content: [{ type: "text", text: "Error: modelUrl is required. Provide a public HTTPS URL to a .glb or .gltf file." }],
+                    content: [{ type: "text", text: `Error: ${validationError}` }],
                     isError: true,
                 };
             }
-            const params = new URLSearchParams();
-            params.set("model", modelUrl);
-            if (!autoRotate)
-                params.set("rotate", "false");
-            if (!ar)
-                params.set("ar", "false");
-            const previewUrl = `https://sceneview.github.io/preview?${params.toString()}`;
-            return {
-                content: [{
-                        type: "text",
-                        text: `## 3D Preview
-
-**[Click to view the 3D model interactively →](${previewUrl})**
-
-The link opens an interactive 3D viewer where you can:
-- 🖱️ Drag to orbit, scroll to zoom
-- 📱 "View in AR" on mobile devices (ARCore/ARKit)
-- 🔗 Share the link with anyone
-
-**Preview URL:** ${previewUrl}
-
-**Model:** ${modelUrl}
-
----
-*Powered by SceneView — 3D & AR for every platform*`,
-                    }],
-            };
+            const result = buildPreviewUrl({ modelUrl, codeSnippet, autoRotate, ar, title });
+            const text = formatPreviewResponse(result);
+            return { content: withDisclaimer([{ type: "text", text }]) };
         }
         default:
             return {

package/dist/preview.js

@@ -0,0 +1,78 @@
+// ─── 3D Preview Link Generator ───────────────────────────────────────────────
+//
+// Generates embeddable preview URLs for sceneview.github.io/preview.
+// Two modes:
+//   1. Model URL → direct model-viewer embed link
+//   2. Code snippet → embed link with default model + code panel
+const PREVIEW_BASE = "https://sceneview.github.io/preview";
+const DEFAULT_MODEL_URL = "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/main/Models/DamagedHelmet/glTF-Binary/DamagedHelmet.glb";
+/**
+ * Build a sceneview.github.io/preview URL from the given options.
+ *
+ * - If `modelUrl` is supplied it is embedded directly.
+ * - If only `codeSnippet` is supplied a default model is used and the code is
+ *   passed via the `code` query parameter so the preview page can show it in a
+ *   companion panel.
+ * - If both are supplied the model URL takes priority and the code is included.
+ */
+export function buildPreviewUrl(options) {
+    const model = options.modelUrl || DEFAULT_MODEL_URL;
+    const hasCode = Boolean(options.codeSnippet?.trim());
+    const title = options.title || (hasCode && !options.modelUrl ? "SceneView Code Preview" : "3D Model Preview");
+    const params = new URLSearchParams();
+    params.set("model", model);
+    if (options.autoRotate === false)
+        params.set("rotate", "false");
+    if (options.ar === false)
+        params.set("ar", "false");
+    if (options.title)
+        params.set("title", options.title);
+    if (hasCode)
+        params.set("code", options.codeSnippet.trim());
+    const previewUrl = `${PREVIEW_BASE}?${params.toString()}`;
+    return { previewUrl, modelUrl: model, hasCode, title };
+}
+/**
+ * Validate preview input — at least one of modelUrl or codeSnippet must be provided.
+ */
+export function validatePreviewInput(modelUrl, codeSnippet) {
+    if (!modelUrl && !codeSnippet) {
+        return "At least one of `modelUrl` or `codeSnippet` is required.";
+    }
+    if (modelUrl) {
+        if (!modelUrl.startsWith("https://") && !modelUrl.startsWith("http://")) {
+            return "modelUrl must be an HTTP(S) URL.";
+        }
+        if (!/\.(glb|gltf)(\?|$)/i.test(modelUrl)) {
+            return "modelUrl should point to a .glb or .gltf file.";
+        }
+    }
+    return null;
+}
+/**
+ * Format the preview result as a rich text response for the MCP tool.
+ */
+export function formatPreviewResponse(result) {
+    const lines = [
+        `## ${result.title}`,
+        ``,
+        `**[Click to view the 3D model interactively \u2192](${result.previewUrl})**`,
+        ``,
+        `The link opens an interactive 3D viewer where you can:`,
+        `- Drag to orbit, scroll to zoom`,
+        `- "View in AR" on mobile devices (ARCore/ARKit)`,
+        `- Share the link with anyone`,
+        ``,
+        `**Preview URL:** ${result.previewUrl}`,
+        ``,
+        `**Model:** ${result.modelUrl}`,
+    ];
+    if (result.hasCode) {
+        lines.push(``);
+        lines.push(`*The code snippet is included in the preview page as a companion panel.*`);
+    }
+    lines.push(``);
+    lines.push(`---`);
+    lines.push(`*Powered by SceneView \u2014 3D & AR for every platform*`);
+    return lines.join("\n");
+}

package/dist/samples.js

@@ -181,6 +181,50 @@ fun PointCloudScreen() {
     ) {
         // Render point cloud model instances at detected positions
     }
+}`,
+    },
+    "ar-face-mesh": {
+        id: "ar-face-mesh",
+        title: "AR Face Mesh",
+        description: "AR face tracking with AugmentedFaceNode — applies a textured mesh overlay to detected faces using the front camera.",
+        tags: ["ar", "face-tracking", "model"],
+        dependency: "io.github.sceneview:arsceneview:3.3.0",
+        prompt: "Create an AR screen that uses the front camera to detect faces and overlay a 3D mesh on them. Use SceneView `io.github.sceneview:arsceneview:3.3.0`.",
+        code: `@Composable
+fun ARFaceMeshScreen() {
+    val engine = rememberEngine()
+    val modelLoader = rememberModelLoader(engine)
+    val materialLoader = rememberMaterialLoader(engine)
+    var trackedFaces by remember { mutableStateOf(listOf<AugmentedFace>()) }
+
+    val faceMaterial = remember(materialLoader) {
+        materialLoader.createColorInstance(
+            color = Color(0.8f, 0.6f, 0.4f, 0.5f),
+            metallic = 0f,
+            roughness = 0.9f
+        )
+    }
+
+    ARScene(
+        modifier = Modifier.fillMaxSize(),
+        engine = engine,
+        modelLoader = modelLoader,
+        sessionFeatures = setOf(Session.Feature.FRONT_CAMERA),
+        sessionConfiguration = { _, config ->
+            config.augmentedFaceMode = Config.AugmentedFaceMode.MESH3D
+        },
+        onSessionUpdated = { session, _ ->
+            trackedFaces = session.getAllTrackables(AugmentedFace::class.java)
+                .filter { it.trackingState == TrackingState.TRACKING }
+        }
+    ) {
+        trackedFaces.forEach { face ->
+            AugmentedFaceNode(
+                augmentedFace = face,
+                meshMaterialInstance = faceMaterial
+            )
+        }
+    }
 }`,
     },
     "gltf-camera": {
@@ -242,6 +286,67 @@ fun CameraManipulatorScreen() {
             ModelNode(modelInstance = instance, scaleToUnits = 1.0f)
         }
     }
+}`,
+    },
+    "camera-animation": {
+        id: "camera-animation",
+        title: "Camera Animation",
+        description: "Animated camera flythrough around a 3D model — smooth orbit using LaunchedEffect and trigonometric interpolation.",
+        tags: ["3d", "camera", "animation", "model"],
+        dependency: "io.github.sceneview:sceneview:3.3.0",
+        prompt: "Create a 3D scene with a camera that automatically orbits around a model in a smooth circle. Include a play/pause button. Use SceneView `io.github.sceneview:sceneview:3.3.0`.",
+        code: `@Composable
+fun CameraAnimationScreen() {
+    val engine = rememberEngine()
+    val modelLoader = rememberModelLoader(engine)
+    val environmentLoader = rememberEnvironmentLoader(engine)
+    var isOrbiting by remember { mutableStateOf(true) }
+    var angle by remember { mutableFloatStateOf(0f) }
+
+    val cameraNode = rememberCameraNode(engine) {
+        position = Position(x = 0f, y = 1.5f, z = 4f)
+        lookAt(Position(0f, 0f, 0f))
+    }
+
+    // Animate camera orbit
+    LaunchedEffect(isOrbiting) {
+        while (isOrbiting) {
+            withFrameNanos { _ ->
+                angle += 0.5f
+                val radians = Math.toRadians(angle.toDouble())
+                cameraNode.position = Position(
+                    x = (4f * sin(radians)).toFloat(),
+                    y = 1.5f,
+                    z = (4f * cos(radians)).toFloat()
+                )
+                cameraNode.lookAt(Position(0f, 0f, 0f))
+            }
+        }
+    }
+
+    Column {
+        Scene(
+            modifier = Modifier.weight(1f).fillMaxWidth(),
+            engine = engine,
+            modelLoader = modelLoader,
+            cameraNode = cameraNode,
+            environment = rememberEnvironment(environmentLoader) {
+                environmentLoader.createHDREnvironment("environments/sky_2k.hdr")
+                    ?: createEnvironment(environmentLoader)
+            },
+            mainLightNode = rememberMainLightNode(engine) { intensity = 100_000f }
+        ) {
+            rememberModelInstance(modelLoader, "models/damaged_helmet.glb")?.let { instance ->
+                ModelNode(modelInstance = instance, scaleToUnits = 1.0f)
+            }
+        }
+        Button(
+            onClick = { isOrbiting = !isOrbiting },
+            modifier = Modifier.align(Alignment.CenterHorizontally).padding(16.dp)
+        ) {
+            Text(if (isOrbiting) "Stop Orbit" else "Start Orbit")
+        }
+    }
 }`,
     },
     "autopilot-demo": {
@@ -466,6 +571,465 @@ fun PostProcessingScreen() {
     }
     // Configure view.bloomOptions, view.vignetteOptions, etc.
     // See samples/post-processing for full interactive controls
+}`,
+    },
+    "video-texture": {
+        id: "video-texture",
+        title: "Video Texture",
+        description: "Video playback on a 3D plane using VideoNode with MediaPlayer — supports looping, chroma-key, and auto-sizing.",
+        tags: ["3d", "video", "model"],
+        dependency: "io.github.sceneview:sceneview:3.3.0",
+        prompt: "Create a 3D scene with a video playing on a floating 3D plane. Include play/pause controls and chroma-key support. Use SceneView `io.github.sceneview:sceneview:3.3.0`.",
+        code: `@Composable
+fun VideoTextureScreen() {
+    val context = LocalContext.current
+    val engine = rememberEngine()
+    var isPlaying by remember { mutableStateOf(true) }
+
+    val player = remember {
+        MediaPlayer().apply {
+            setDataSource(context, Uri.parse("android.resource://\${context.packageName}/raw/video"))
+            isLooping = true
+            prepare()
+            start()
+        }
+    }
+    DisposableEffect(Unit) { onDispose { player.release() } }
+
+    Column {
+        Scene(
+            modifier = Modifier.weight(1f).fillMaxWidth(),
+            engine = engine
+        ) {
+            VideoNode(
+                player = player,
+                // size = null auto-sizes from video aspect ratio (longer edge = 1 unit)
+                position = Position(z = -2f),
+                chromaKeyColor = null // set to android.graphics.Color.GREEN for green-screen
+            )
+        }
+        Row(
+            modifier = Modifier.fillMaxWidth().padding(16.dp),
+            horizontalArrangement = Arrangement.Center,
+            verticalAlignment = Alignment.CenterVertically
+        ) {
+            Button(onClick = {
+                if (isPlaying) player.pause() else player.start()
+                isPlaying = !isPlaying
+            }) {
+                Text(if (isPlaying) "Pause" else "Play")
+            }
+        }
+    }
+}`,
+    },
+    "multi-model-scene": {
+        id: "multi-model-scene",
+        title: "Multi-Model Scene",
+        description: "Scene with multiple 3D models loaded independently, positioned and scaled to create a complete environment.",
+        tags: ["3d", "model", "multi-model", "environment"],
+        dependency: "io.github.sceneview:sceneview:3.3.0",
+        prompt: "Create a 3D scene that loads multiple GLB models (a car, a building, and trees) and positions them to form a street scene. Use SceneView `io.github.sceneview:sceneview:3.3.0`.",
+        code: `@Composable
+fun MultiModelScreen() {
+    val engine = rememberEngine()
+    val modelLoader = rememberModelLoader(engine)
+    val materialLoader = rememberMaterialLoader(engine)
+    val environmentLoader = rememberEnvironmentLoader(engine)
+
+    Scene(
+        modifier = Modifier.fillMaxSize(),
+        engine = engine,
+        modelLoader = modelLoader,
+        cameraManipulator = rememberCameraManipulator(
+            orbitHomePosition = Position(x = 0f, y = 3f, z = 8f),
+            targetPosition = Position(0f, 0f, 0f)
+        ),
+        environment = rememberEnvironment(environmentLoader) {
+            environmentLoader.createHDREnvironment("environments/sky_2k.hdr")
+                ?: createEnvironment(environmentLoader)
+        },
+        mainLightNode = rememberMainLightNode(engine) { intensity = 100_000f }
+    ) {
+        // Ground plane
+        val groundMat = remember(materialLoader) {
+            materialLoader.createColorInstance(Color.DarkGray, roughness = 0.9f)
+        }
+        PlaneNode(size = Size(20f, 20f), materialInstance = groundMat)
+
+        // Car in the center
+        rememberModelInstance(modelLoader, "models/car.glb")?.let { car ->
+            ModelNode(
+                modelInstance = car,
+                scaleToUnits = 2.0f,
+                position = Position(x = 0f, y = 0f, z = 0f),
+                autoAnimate = true
+            )
+        }
+
+        // Building on the left
+        rememberModelInstance(modelLoader, "models/building.glb")?.let { building ->
+            ModelNode(
+                modelInstance = building,
+                scaleToUnits = 5.0f,
+                position = Position(x = -6f, y = 0f, z = -3f)
+            )
+        }
+
+        // Trees along the right side
+        for (i in 0..2) {
+            rememberModelInstance(modelLoader, "models/tree.glb")?.let { tree ->
+                ModelNode(
+                    modelInstance = tree,
+                    scaleToUnits = 3.0f,
+                    position = Position(x = 5f, y = 0f, z = i * -3f)
+                )
+            }
+        }
+    }
+}`,
+    },
+    "gesture-interaction": {
+        id: "gesture-interaction",
+        title: "Gesture Interaction",
+        description: "Full gesture handling — tap to select, double-tap to scale, long-press for info, pinch-to-scale, drag-to-move on editable nodes.",
+        tags: ["3d", "gestures", "model"],
+        dependency: "io.github.sceneview:sceneview:3.3.0",
+        prompt: "Create a 3D scene with a model that responds to tap (select), double-tap (scale up), long-press (show info), and supports pinch-to-scale and drag-to-move. Use SceneView `io.github.sceneview:sceneview:3.3.0`.",
+        code: `@Composable
+fun GestureInteractionScreen() {
+    val engine = rememberEngine()
+    val modelLoader = rememberModelLoader(engine)
+    val environmentLoader = rememberEnvironmentLoader(engine)
+    var selectedNode by remember { mutableStateOf<String?>(null) }
+    var infoText by remember { mutableStateOf("Tap a model to select it") }
+
+    Box(modifier = Modifier.fillMaxSize()) {
+        Scene(
+            modifier = Modifier.fillMaxSize(),
+            engine = engine,
+            modelLoader = modelLoader,
+            cameraManipulator = rememberCameraManipulator(),
+            environment = rememberEnvironment(environmentLoader) {
+                environmentLoader.createHDREnvironment("environments/sky_2k.hdr")
+                    ?: createEnvironment(environmentLoader)
+            },
+            onGestureListener = rememberOnGestureListener(
+                onSingleTapConfirmed = { event, node ->
+                    selectedNode = node?.name
+                    infoText = if (node != null) "Selected: \${node.name}" else "Tap a model to select it"
+                },
+                onDoubleTap = { event, node ->
+                    node?.let {
+                        it.scale = if (it.scale.x > 1.5f) Scale(1f) else Scale(2f)
+                        infoText = "Double-tap: toggled scale"
+                    }
+                },
+                onLongPress = { event, node ->
+                    node?.let {
+                        infoText = "Position: \${it.worldPosition}, Scale: \${it.scale}"
+                    }
+                }
+            )
+        ) {
+            rememberModelInstance(modelLoader, "models/damaged_helmet.glb")?.let { instance ->
+                ModelNode(
+                    modelInstance = instance,
+                    scaleToUnits = 1.0f,
+                    isEditable = true, // enables pinch-to-scale and drag-to-move
+                    autoAnimate = true
+                )
+            }
+        }
+
+        // Info overlay
+        Text(
+            text = infoText,
+            modifier = Modifier.align(Alignment.TopCenter).padding(24.dp)
+                .background(MaterialTheme.colorScheme.surface.copy(alpha = 0.8f), RoundedCornerShape(8.dp))
+                .padding(12.dp),
+            style = MaterialTheme.typography.bodyMedium
+        )
+    }
+}`,
+    },
+    "environment-lighting": {
+        id: "environment-lighting",
+        title: "Environment & Lighting",
+        description: "Complete lighting setup — HDR environment (IBL + skybox), main directional light, point light, and spot light with LightNode.",
+        tags: ["3d", "environment", "lighting", "model"],
+        dependency: "io.github.sceneview:sceneview:3.3.0",
+        prompt: "Create a 3D scene with full HDR environment lighting (IBL + skybox), a directional sun light, a red point light, and a blue spot light. Use SceneView `io.github.sceneview:sceneview:3.3.0`.",
+        code: `@Composable
+fun EnvironmentLightingScreen() {
+    val engine = rememberEngine()
+    val modelLoader = rememberModelLoader(engine)
+    val materialLoader = rememberMaterialLoader(engine)
+    val environmentLoader = rememberEnvironmentLoader(engine)
+
+    Scene(
+        modifier = Modifier.fillMaxSize(),
+        engine = engine,
+        modelLoader = modelLoader,
+        cameraManipulator = rememberCameraManipulator(
+            orbitHomePosition = Position(x = 0f, y = 2f, z = 5f),
+            targetPosition = Position(0f, 0f, 0f)
+        ),
+        // HDR environment provides both IBL (indirect lighting) and skybox (background)
+        environment = rememberEnvironment(environmentLoader) {
+            environmentLoader.createHDREnvironment("environments/sky_2k.hdr")
+                ?: createEnvironment(environmentLoader)
+        },
+        // Main directional light (sun)
+        mainLightNode = rememberMainLightNode(engine) {
+            intensity = 100_000f
+            // castShadows is true by default for the main light
+        }
+    ) {
+        // Floor to receive shadows
+        val floorMat = remember(materialLoader) {
+            materialLoader.createColorInstance(Color.LightGray, roughness = 0.8f)
+        }
+        PlaneNode(size = Size(10f, 10f), materialInstance = floorMat)
+
+        // Model
+        rememberModelInstance(modelLoader, "models/damaged_helmet.glb")?.let { instance ->
+            ModelNode(modelInstance = instance, scaleToUnits = 1.0f, position = Position(y = 0.5f))
+        }
+
+        // Red point light on the left
+        LightNode(
+            type = LightManager.Type.POINT,
+            apply = {
+                color(1.0f, 0.2f, 0.2f)
+                intensity(200_000f)
+                falloff(5.0f)
+            },
+            position = Position(x = -2f, y = 2f, z = 1f)
+        )
+
+        // Blue spot light on the right
+        LightNode(
+            type = LightManager.Type.SPOT,
+            apply = {
+                color(0.2f, 0.4f, 1.0f)
+                intensity(300_000f)
+                falloff(8.0f)
+                castShadows(true)
+            },
+            position = Position(x = 2f, y = 3f, z = 1f)
+        )
+    }
+}`,
+    },
+    "procedural-geometry": {
+        id: "procedural-geometry",
+        title: "Procedural Geometry",
+        description: "Procedural shapes — CubeNode, SphereNode, CylinderNode, PlaneNode — with PBR materials (metallic, roughness, color).",
+        tags: ["3d", "geometry", "model"],
+        dependency: "io.github.sceneview:sceneview:3.3.0",
+        prompt: "Create a 3D scene showing procedural geometry shapes (cube, sphere, cylinder, plane) with different PBR materials. No model files needed. Use SceneView `io.github.sceneview:sceneview:3.3.0`.",
+        code: `@Composable
+fun ProceduralGeometryScreen() {
+    val engine = rememberEngine()
+    val materialLoader = rememberMaterialLoader(engine)
+    val environmentLoader = rememberEnvironmentLoader(engine)
+
+    Scene(
+        modifier = Modifier.fillMaxSize(),
+        engine = engine,
+        cameraManipulator = rememberCameraManipulator(
+            orbitHomePosition = Position(x = 0f, y = 2f, z = 6f),
+            targetPosition = Position(0f, 0.5f, 0f)
+        ),
+        environment = rememberEnvironment(environmentLoader) {
+            environmentLoader.createHDREnvironment("environments/sky_2k.hdr")
+                ?: createEnvironment(environmentLoader)
+        },
+        mainLightNode = rememberMainLightNode(engine) { intensity = 100_000f }
+    ) {
+        // Floor
+        val floorMat = remember(materialLoader) {
+            materialLoader.createColorInstance(Color.DarkGray, roughness = 0.9f)
+        }
+        PlaneNode(size = Size(8f, 8f), materialInstance = floorMat)
+
+        // Red matte cube
+        val redMat = remember(materialLoader) {
+            materialLoader.createColorInstance(Color.Red, metallic = 0f, roughness = 0.6f)
+        }
+        CubeNode(
+            size = Size(0.6f),
+            center = Position(0f, 0.3f, 0f),
+            materialInstance = redMat,
+            position = Position(x = -2f)
+        )
+
+        // Chrome sphere
+        val chromeMat = remember(materialLoader) {
+            materialLoader.createColorInstance(Color.Gray, metallic = 1f, roughness = 0.05f, reflectance = 0.9f)
+        }
+        SphereNode(
+            radius = 0.4f,
+            materialInstance = chromeMat,
+            position = Position(x = -0.7f, y = 0.4f)
+        )
+
+        // Green cylinder
+        val greenMat = remember(materialLoader) {
+            materialLoader.createColorInstance(Color.Green, metallic = 0.2f, roughness = 0.4f)
+        }
+        CylinderNode(
+            radius = 0.25f,
+            height = 0.8f,
+            materialInstance = greenMat,
+            position = Position(x = 0.7f, y = 0.4f)
+        )
+
+        // Gold sphere
+        val goldMat = remember(materialLoader) {
+            materialLoader.createColorInstance(
+                Color(1f, 0.84f, 0f),
+                metallic = 1f,
+                roughness = 0.3f
+            )
+        }
+        SphereNode(
+            radius = 0.35f,
+            materialInstance = goldMat,
+            position = Position(x = 2f, y = 0.35f)
+        )
+    }
+}`,
+    },
+    "compose-ui-3d": {
+        id: "compose-ui-3d",
+        title: "Compose UI in 3D",
+        description: "Embed interactive Jetpack Compose UI (Cards, Buttons, Text) inside 3D space using ViewNode.",
+        tags: ["3d", "compose-ui", "text"],
+        dependency: "io.github.sceneview:sceneview:3.3.0",
+        prompt: "Create a 3D scene with interactive Compose UI elements (Card with text and a button) floating in 3D space using ViewNode. Use SceneView `io.github.sceneview:sceneview:3.3.0`.",
+        code: `@Composable
+fun ComposeUI3DScreen() {
+    val engine = rememberEngine()
+    val modelLoader = rememberModelLoader(engine)
+    val windowManager = rememberViewNodeManager()
+    var clickCount by remember { mutableIntStateOf(0) }
+
+    Scene(
+        modifier = Modifier.fillMaxSize(),
+        engine = engine,
+        modelLoader = modelLoader,
+        cameraManipulator = rememberCameraManipulator(),
+        viewNodeWindowManager = windowManager
+    ) {
+        // 3D model behind the UI
+        rememberModelInstance(modelLoader, "models/damaged_helmet.glb")?.let { instance ->
+            ModelNode(modelInstance = instance, scaleToUnits = 1.0f, position = Position(z = -1f))
+        }
+
+        // Floating Compose Card in 3D space
+        ViewNode(
+            windowManager = windowManager,
+            position = Position(x = 0f, y = 1.2f, z = 0.5f)
+        ) {
+            Card(
+                modifier = Modifier.width(200.dp).padding(8.dp),
+                colors = CardDefaults.cardColors(
+                    containerColor = MaterialTheme.colorScheme.surface.copy(alpha = 0.9f)
+                )
+            ) {
+                Column(modifier = Modifier.padding(16.dp)) {
+                    Text("Hello 3D World!", style = MaterialTheme.typography.titleMedium)
+                    Text("Clicks: \$clickCount", style = MaterialTheme.typography.bodySmall)
+                    Spacer(Modifier.height(8.dp))
+                    Button(onClick = { clickCount++ }) {
+                        Text("Click Me")
+                    }
+                }
+            }
+        }
+    }
+}`,
+    },
+    "node-hierarchy": {
+        id: "node-hierarchy",
+        title: "Node Hierarchy",
+        description: "Parent-child node relationships — a spinning solar system with planet groups orbiting a central sun.",
+        tags: ["3d", "hierarchy", "geometry", "animation"],
+        dependency: "io.github.sceneview:sceneview:3.3.0",
+        prompt: "Create a 3D solar system where planets orbit a sun using parent-child node hierarchies. Each planet group rotates independently. Use SceneView `io.github.sceneview:sceneview:3.3.0`.",
+        code: `@Composable
+fun NodeHierarchyScreen() {
+    val engine = rememberEngine()
+    val materialLoader = rememberMaterialLoader(engine)
+    val environmentLoader = rememberEnvironmentLoader(engine)
+    var earthAngle by remember { mutableFloatStateOf(0f) }
+    var marsAngle by remember { mutableFloatStateOf(0f) }
+
+    // Animate planet orbits
+    LaunchedEffect(Unit) {
+        while (true) {
+            withFrameNanos { _ ->
+                earthAngle += 0.3f
+                marsAngle += 0.18f
+            }
+        }
+    }
+
+    Scene(
+        modifier = Modifier.fillMaxSize(),
+        engine = engine,
+        cameraManipulator = rememberCameraManipulator(
+            orbitHomePosition = Position(x = 0f, y = 4f, z = 8f),
+            targetPosition = Position(0f, 0f, 0f)
+        ),
+        environment = rememberEnvironment(environmentLoader) {
+            environmentLoader.createHDREnvironment("environments/sky_2k.hdr")
+                ?: createEnvironment(environmentLoader)
+        }
+    ) {
+        // Sun (center)
+        val sunMat = remember(materialLoader) {
+            materialLoader.createColorInstance(Color.Yellow, metallic = 0f, roughness = 1f)
+        }
+        SphereNode(radius = 0.5f, materialInstance = sunMat)
+
+        // Earth orbit group — parent node rotates, child offset creates orbit
+        Node(rotation = Rotation(y = earthAngle)) {
+            // Earth sphere
+            val earthMat = remember(materialLoader) {
+                materialLoader.createColorInstance(Color.Blue, metallic = 0f, roughness = 0.7f)
+            }
+            SphereNode(radius = 0.2f, materialInstance = earthMat, position = Position(x = 2.5f))
+
+            // Moon orbits Earth (nested hierarchy)
+            Node(position = Position(x = 2.5f), rotation = Rotation(y = earthAngle * 3f)) {
+                val moonMat = remember(materialLoader) {
+                    materialLoader.createColorInstance(Color.LightGray, metallic = 0f, roughness = 0.9f)
+                }
+                SphereNode(radius = 0.06f, materialInstance = moonMat, position = Position(x = 0.4f))
+            }
+        }
+
+        // Mars orbit group
+        Node(rotation = Rotation(y = marsAngle)) {
+            val marsMat = remember(materialLoader) {
+                materialLoader.createColorInstance(Color.Red, metallic = 0f, roughness = 0.8f)
+            }
+            SphereNode(radius = 0.15f, materialInstance = marsMat, position = Position(x = 4f))
+        }
+
+        // Sun light
+        LightNode(
+            type = LightManager.Type.POINT,
+            apply = {
+                color(1.0f, 0.95f, 0.8f)
+                intensity(500_000f)
+                falloff(15.0f)
+            }
+        )
+    }
 }`,
     },
     // ─── iOS Samples ────────────────────────────────────────────────────────────

package/llms.txt

@@ -2247,12 +2247,123 @@ ARSceneView.checkSupport { supported ->
 
 ---
 
+## Android XR (Planned)
+
+SceneView can be used inside Android XR's spatial layout system via the Jetpack XR SDK
+(Developer Preview). The integration embeds SceneView's `Scene {}` composable inside a
+`SpatialPanel`, giving full Filament rendering inside an XR spatial panel.
+
+**Dependencies (in addition to SceneView):**
+```kotlin
+implementation("androidx.xr.scenecore:scenecore:1.0.0-alpha12")
+implementation("androidx.xr.compose:compose:1.0.0-alpha12")
+```
+
+**Basic pattern:**
+```kotlin
+Subspace {
+    SpatialPanel(SubspaceModifier.width(1200.dp).height(800.dp)) {
+        val engine = rememberEngine()
+        val modelLoader = rememberModelLoader(engine)
+        Scene(modifier = Modifier.fillMaxSize(), engine = engine, modelLoader = modelLoader) {
+            rememberModelInstance(modelLoader, "models/helmet.glb")?.let {
+                ModelNode(modelInstance = it)
+            }
+        }
+    }
+}
+```
+
+Key XR composables: `Subspace`, `SpatialPanel`, `SpatialRow`, `SpatialColumn`, `Orbiter`,
+`SceneCoreEntity`. SceneCore entities: `GltfModelEntity`, `PanelEntity`, `AnchorEntity`,
+`SpatialEnvironment`. Status: **experimental / planned** — Jetpack XR SDK is alpha.
+
+---
+
+## visionOS Spatial Computing (Planned)
+
+SceneViewSwift targets visionOS 1+ via RealityKit. Spatial features are planned for future
+releases, building on the existing `SceneView` and node types.
+
+### Scene Types
+
+| Type | Style | Description | SceneViewSwift |
+|---|---|---|---|
+| Window | 2D | Standard SwiftUI window in shared space | `SceneView { }` (existing) |
+| Volume | 3D bounded | Fixed-size 3D container in shared space | `VolumetricSceneView` (planned) |
+| Immersive Space | `.mixed` | Virtual content blends with passthrough | `ImmersiveSceneView` (planned) |
+| Immersive Space | `.progressive` | Partial passthrough replacement | `ImmersiveSceneView` (planned) |
+| Immersive Space | `.full` | Fully virtual, passthrough off | `ImmersiveSceneView` (planned) |
+
+### Hand Tracking (visionOS 1+, Full Space required)
+
+ARKit `HandTrackingProvider` tracks 27 joints per hand at display refresh rate.
+Requires `NSHandsTrackingUsageDescription` in Info.plist and a `SpatialTrackingSession`.
+
+**Planned API:**
+```swift
+ImmersiveSceneView { root in /* content */ }
+    .handTracking(enabled: true)
+    .onHandUpdate { hands in
+        if let d = hands.jointDistance(.thumbTip, .indexFingerTip, hand: .right), d < 0.02 {
+            // Pinch detected
+        }
+    }
+```
+
+### Spatial Anchors
+
+`SpatialTrackingSession` (visionOS 2.0+) unlocks ARKit data in RealityKit: anchor
+geometry extents, real-world offset, and scene understanding mesh.
+
+**Planned API:**
+```swift
+// World anchor
+SpatialAnchorNode.world(position: SIMD3<Float>(0, 1, -2))
+
+// Plane anchor (on detected surface)
+SpatialAnchorNode.plane(alignment: .horizontal)
+
+// Hand anchor (attached to a joint)
+SpatialAnchorNode.hand(.right, joint: .indexFingerTip)
+```
+
+### Scene Understanding
+
+Real-time mesh of surroundings enabling collision, physics, surface classification
+(floor, wall, ceiling, table, seat, door, window), and environment occlusion.
+
+### Object Manipulation (visionOS 26)
+
+`ManipulationComponent` enables look, tap, drag, rotate, scale on entities with a
+single call. `EnvironmentBlendingComponent` for real-world occlusion.
+`MeshInstancesComponent` for efficient GPU instanced rendering.
+
+**Planned API:**
+```swift
+let model = try await ModelNode.load("models/chair.usdz")
+model.enableManipulation()  // look + grab + drag + rotate + scale via system gestures
+```
+
+### Cross-Platform Mapping (visionOS <-> Android XR)
+
+| Feature | visionOS | Android XR |
+|---|---|---|
+| Spatial container | Volume (`.volumetric`) | `SpatialPanel` |
+| Immersive mode | `ImmersiveSpace` | `SpatialEnvironment` |
+| Hand tracking | `HandTrackingProvider` | Jetpack XR hand tracking |
+| Spatial anchors | `WorldAnchor` | `AnchorEntity` (SceneCore) |
+| Scene understanding | Scene mesh + classification | Perception APIs |
+
+---
+
 ## Platform Coverage Summary
 
 | Platform | Renderer | Framework | Sample | Status |
 |---|---|---|---|---|
 | Android | Filament | Jetpack Compose | `samples/android-demo` | Stable |
 | Android TV | Filament | Compose TV | `samples/android-tv-demo` | Alpha |
+| Android XR | Filament + SceneCore | Compose for XR | — | Planned |
 | iOS | RealityKit | SwiftUI | `samples/ios-demo` | Alpha |
 | macOS | RealityKit | SwiftUI | via SceneViewSwift | Alpha |
 | visionOS | RealityKit | SwiftUI | via SceneViewSwift | Alpha |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sceneview-mcp",
-  "version": "3.4.6",
+  "version": "3.4.8",
   "mcpName": "io.github.sceneview/mcp",
   "description": "MCP server for SceneView — cross-platform 3D & AR SDK for Android and iOS. Give Claude the full SceneView SDK so it writes correct, compilable code.",
   "keywords": [
@@ -43,6 +43,7 @@
     "dist/migration.js",
     "dist/node-reference.js",
     "dist/samples.js",
+    "dist/preview.js",
     "dist/validator.js",
     "llms.txt"
   ],