sceneview-mcp 3.0.0 → 3.0.2

package/dist/migration.js

@@ -0,0 +1,248 @@
+export const MIGRATION_GUIDE = `# SceneView 2.x → 3.0 Migration Guide
+
+SceneView 3.0 is a full rewrite from Android Views to **Jetpack Compose**. Nearly every public API changed. This guide covers every breaking change and how to fix it.
+
+---
+
+## 1. Gradle dependency
+
+| 2.x | 3.0 |
+|-----|-----|
+| \`io.github.sceneview:sceneview:2.x.x\` | \`io.github.sceneview:sceneview:3.0.0\` |
+| \`io.github.sceneview:arsceneview:2.x.x\` | \`io.github.sceneview:arsceneview:3.0.0\` |
+
+---
+
+## 2. Root composable names
+
+| 2.x | 3.0 |
+|-----|-----|
+| \`SceneView(…)\` | \`Scene(…)\` |
+| \`ArSceneView(…)\` | \`ARScene(…)\` |
+
+**Before:**
+\`\`\`kotlin
+SceneView(modifier = Modifier.fillMaxSize())
+\`\`\`
+
+**After:**
+\`\`\`kotlin
+val engine = rememberEngine()
+Scene(modifier = Modifier.fillMaxSize(), engine = engine)
+\`\`\`
+
+---
+
+## 3. Engine lifecycle
+
+In 2.x the engine was managed internally. In 3.0 you own it — use \`rememberEngine()\` which ties it to the composition lifecycle.
+
+| 2.x | 3.0 |
+|-----|-----|
+| Engine implicit | \`val engine = rememberEngine()\` |
+| Never destroy manually | Never call \`engine.destroy()\` — \`rememberEngine\` does it |
+
+---
+
+## 4. Model loading
+
+| 2.x | 3.0 |
+|-----|-----|
+| \`modelLoader.loadModelAsync(path) { … }\` | \`rememberModelInstance(modelLoader, path)\` (returns \`null\` while loading) |
+| \`modelLoader.loadModel(path)\` | \`modelLoader.loadModelInstanceAsync(path)\` (imperative) |
+| \`ModelRenderable.builder()\` | Removed — use GLB/glTF assets |
+
+**Before:**
+\`\`\`kotlin
+var modelInstance by remember { mutableStateOf<ModelInstance?>(null) }
+LaunchedEffect(Unit) {
+    modelInstance = modelLoader.loadModelAsync("models/chair.glb")
+}
+\`\`\`
+
+**After:**
+\`\`\`kotlin
+Scene(engine = engine, modelLoader = modelLoader) {
+    rememberModelInstance(modelLoader, "models/chair.glb")?.let { instance ->
+        ModelNode(modelInstance = instance, scaleToUnits = 1.0f)
+    }
+}
+\`\`\`
+
+---
+
+## 5. Node hierarchy — imperative → declarative DSL
+
+In 2.x nodes were added imperatively (\`scene.addChild(node)\`). In 3.0 nodes are declared as composables inside \`Scene { }\` or \`ARScene { }\`.
+
+**Before:**
+\`\`\`kotlin
+val modelNode = ModelNode().apply {
+    loadModelGlbAsync(
+        glbFileLocation = "models/chair.glb",
+        scaleToUnits = 1f,
+    )
+}
+sceneView.addChildNode(modelNode)
+\`\`\`
+
+**After:**
+\`\`\`kotlin
+Scene(engine = engine, modelLoader = modelLoader) {
+    rememberModelInstance(modelLoader, "models/chair.glb")?.let { instance ->
+        ModelNode(modelInstance = instance, scaleToUnits = 1f)
+    }
+}
+\`\`\`
+
+---
+
+## 6. Removed nodes and replacements
+
+| 2.x | 3.0 replacement |
+|-----|-----------------|
+| \`TransformableNode\` | Set \`isEditable = true\` on \`ModelNode\` |
+| \`PlacementNode\` | \`AnchorNode(anchor = hitResult.createAnchor())\` + \`HitResultNode\` |
+| \`ViewRenderable\` | \`ViewNode\` with a \`@Composable\` content lambda |
+| \`AnchorNode()\` (no-arg) | \`AnchorNode(anchor = hitResult.createAnchor())\` |
+
+**TransformableNode:**
+\`\`\`kotlin
+// Before
+val node = TransformableNode(transformationSystem).apply {
+    setParent(anchorNode)
+}
+
+// After
+ModelNode(
+    modelInstance = instance,
+    scaleToUnits = 1f,
+    isEditable = true  // enables pinch-to-scale + drag-to-rotate
+)
+\`\`\`
+
+**ViewRenderable → ViewNode:**
+\`\`\`kotlin
+// Before
+ViewRenderable.builder()
+    .setView(context, R.layout.my_layout)
+    .build()
+    .thenAccept { renderable -> … }
+
+// After
+val windowManager = rememberViewNodeManager()
+Scene(viewNodeWindowManager = windowManager) {
+    ViewNode(windowManager = windowManager) {
+        Card { Text("Hello 3D World!") }
+    }
+}
+\`\`\`
+
+---
+
+## 7. Light configuration
+
+LightNode's \`apply\` is a **named parameter** (not a trailing lambda). This is the most common silent breakage after migrating.
+
+\`\`\`kotlin
+// WRONG — trailing lambda is silently ignored
+LightNode(engine = engine, type = LightManager.Type.DIRECTIONAL) {
+    intensity(100_000f)
+}
+
+// CORRECT
+LightNode(
+    engine = engine,
+    type = LightManager.Type.DIRECTIONAL,
+    apply = {
+        intensity(100_000f)
+        castShadows(true)
+    }
+)
+\`\`\`
+
+---
+
+## 8. Environment / IBL loading
+
+| 2.x | 3.0 |
+|-----|-----|
+| \`environmentLoader.loadEnvironment(path)\` | \`environmentLoader.createHDREnvironment(path)\` |
+
+\`\`\`kotlin
+// 3.0
+val environmentLoader = rememberEnvironmentLoader(engine)
+Scene(
+    environment = rememberEnvironment(environmentLoader) {
+        environmentLoader.createHDREnvironment("environments/sky_2k.hdr")!!
+    }
+) { … }
+\`\`\`
+
+---
+
+## 9. AR session configuration
+
+In 3.0 \`sessionConfiguration\` is a lambda parameter on \`ARScene\` (not a separate builder).
+
+\`\`\`kotlin
+ARScene(
+    engine = engine,
+    modelLoader = modelLoader,
+    sessionConfiguration = { session, config ->
+        config.depthMode =
+            if (session.isDepthModeSupported(Config.DepthMode.AUTOMATIC))
+                Config.DepthMode.AUTOMATIC else Config.DepthMode.DISABLED
+        config.instantPlacementMode = Config.InstantPlacementMode.LOCAL_Y_UP
+        config.lightEstimationMode = Config.LightEstimationMode.ENVIRONMENTAL_HDR
+    }
+) { … }
+\`\`\`
+
+---
+
+## 10. AR anchors (no more worldPosition hacks)
+
+| 2.x pattern | 3.0 |
+|-------------|-----|
+| \`node.worldPosition = hitResult.hitPose.position\` | \`AnchorNode(anchor = hitResult.createAnchor())\` |
+
+Plain nodes whose \`worldPosition\` is set manually will drift when ARCore remaps its coordinate system. \`AnchorNode\` compensates automatically.
+
+---
+
+## 11. Shadows
+
+In 3.0, \`ARScene\` has shadows enabled by default via \`createARView()\`. For \`Scene\` (3D only), shadows are disabled by default — enable with:
+
+\`\`\`kotlin
+Scene(
+    view = rememberView(engine).also { it.setShadowingEnabled(true) },
+    …
+)
+\`\`\`
+
+---
+
+## 12. Camera
+
+| 2.x | 3.0 |
+|-----|-----|
+| \`CameraManipulator\` set on the View | \`cameraManipulator = rememberCameraManipulator()\` on \`Scene\` |
+| Custom camera via \`setCameraNode\` | \`cameraNode = rememberCameraNode(engine) { … }\` on \`Scene\` |
+
+---
+
+## Checklist
+
+- [ ] Replace \`SceneView(…)\` → \`Scene(engine = rememberEngine(), …)\`
+- [ ] Replace \`ArSceneView(…)\` → \`ARScene(engine = rememberEngine(), …)\`
+- [ ] Replace \`modelLoader.loadModelAsync\` → \`rememberModelInstance\`
+- [ ] Add null-check on every \`rememberModelInstance\` result
+- [ ] Replace \`TransformableNode\` → \`isEditable = true\`
+- [ ] Replace \`PlacementNode\` → \`AnchorNode\` + \`HitResultNode\`
+- [ ] Replace \`ViewRenderable\` → \`ViewNode\` with Compose lambda
+- [ ] Fix \`LightNode { … }\` → \`LightNode(apply = { … })\`
+- [ ] Remove manual \`engine.destroy()\` calls
+- [ ] Replace manual \`worldPosition\` in AR → \`AnchorNode\`
+`;

package/dist/migration.test.js

@@ -0,0 +1,50 @@
+import { describe, it, expect } from "vitest";
+import { MIGRATION_GUIDE } from "./migration.js";
+describe("MIGRATION_GUIDE", () => {
+    it("is a non-empty string", () => {
+        expect(typeof MIGRATION_GUIDE).toBe("string");
+        expect(MIGRATION_GUIDE.length).toBeGreaterThan(500);
+    });
+    it("covers composable renames (SceneView → Scene, ArSceneView → ARScene)", () => {
+        expect(MIGRATION_GUIDE).toContain("SceneView");
+        expect(MIGRATION_GUIDE).toContain("Scene");
+        expect(MIGRATION_GUIDE).toContain("ArSceneView");
+        expect(MIGRATION_GUIDE).toContain("ARScene");
+    });
+    it("covers model loading migration (loadModelAsync → rememberModelInstance)", () => {
+        expect(MIGRATION_GUIDE).toContain("loadModelAsync");
+        expect(MIGRATION_GUIDE).toContain("rememberModelInstance");
+    });
+    it("covers removed nodes", () => {
+        expect(MIGRATION_GUIDE).toContain("TransformableNode");
+        expect(MIGRATION_GUIDE).toContain("PlacementNode");
+        expect(MIGRATION_GUIDE).toContain("ViewRenderable");
+    });
+    it("covers LightNode named apply parameter gotcha", () => {
+        expect(MIGRATION_GUIDE).toContain("apply");
+        expect(MIGRATION_GUIDE).toContain("LightNode");
+        expect(MIGRATION_GUIDE).toContain("trailing lambda");
+    });
+    it("covers engine lifecycle (rememberEngine)", () => {
+        expect(MIGRATION_GUIDE).toContain("rememberEngine");
+        expect(MIGRATION_GUIDE).toContain("engine.destroy");
+    });
+    it("covers AR anchor drift (worldPosition → AnchorNode)", () => {
+        expect(MIGRATION_GUIDE).toContain("worldPosition");
+        expect(MIGRATION_GUIDE).toContain("AnchorNode");
+        expect(MIGRATION_GUIDE).toContain("drift");
+    });
+    it("covers gradle dependency changes", () => {
+        expect(MIGRATION_GUIDE).toContain("io.github.sceneview:sceneview:3.0.0");
+        expect(MIGRATION_GUIDE).toContain("io.github.sceneview:arsceneview:3.0.0");
+    });
+    it("includes a migration checklist", () => {
+        expect(MIGRATION_GUIDE).toContain("Checklist");
+        expect(MIGRATION_GUIDE).toContain("- [ ]");
+    });
+    it("includes before/after code examples", () => {
+        expect(MIGRATION_GUIDE).toContain("Before");
+        expect(MIGRATION_GUIDE).toContain("After");
+        expect(MIGRATION_GUIDE).toContain("```kotlin");
+    });
+});

package/dist/samples.js

@@ -3,6 +3,7 @@ export const SAMPLES = {
         id: "model-viewer",
         title: "3D Model Viewer",
         description: "Full-screen 3D scene with a GLB model, HDR environment, and orbit camera",
+        tags: ["3d", "model", "environment", "camera"],
         dependency: "io.github.sceneview:sceneview:3.0.0",
         prompt: "Create an Android Compose screen called `ModelViewerScreen` that loads a GLB file from assets/models/my_model.glb and displays it in a full-screen 3D scene with an orbit camera (drag to rotate, pinch to zoom). Add an HDR environment from assets/environments/sky_2k.hdr for realistic lighting. Use SceneView `io.github.sceneview:sceneview:3.0.0`.",
         code: `@Composable
@@ -30,12 +31,69 @@ fun ModelViewerScreen() {
             )
         }
     }
+}`,
+    },
+    "geometry-scene": {
+        id: "geometry-scene",
+        title: "3D Geometry Scene",
+        description: "Procedural 3D scene using primitive geometry nodes (cube, sphere, plane) — no GLB required",
+        tags: ["3d", "geometry", "animation"],
+        dependency: "io.github.sceneview:sceneview:3.0.0",
+        prompt: "Create an Android Compose screen called `GeometrySceneScreen` that renders a full-screen 3D scene with a red rotating cube, a metallic blue sphere, and a green floor plane. No model files — use SceneView built-in geometry nodes. Orbit camera. Use SceneView `io.github.sceneview:sceneview:3.0.0`.",
+        code: `@Composable
+fun GeometrySceneScreen() {
+    val engine = rememberEngine()
+    val materialLoader = rememberMaterialLoader(engine)
+    val t = rememberInfiniteTransition(label = "spin")
+    val angle by t.animateFloat(
+        initialValue = 0f, targetValue = 360f,
+        animationSpec = infiniteRepeatable(tween(4_000, easing = LinearEasing)),
+        label = "angle"
+    )
+
+    Scene(
+        modifier = Modifier.fillMaxSize(),
+        engine = engine,
+        materialLoader = materialLoader,
+        mainLightNode = rememberMainLightNode(engine) { intensity(80_000f) },
+        cameraManipulator = rememberCameraManipulator()
+    ) {
+        // Rotating red cube
+        CubeNode(
+            engine,
+            size = Size(0.5f, 0.5f, 0.5f),
+            materialInstance = materialLoader.createColorInstance(
+                Color.Red, metallic = 0f, roughness = 0.5f
+            ),
+            position = Position(x = -0.6f),
+            rotation = Rotation(y = angle)
+        )
+        // Metallic blue sphere
+        SphereNode(
+            engine,
+            radius = 0.3f,
+            materialInstance = materialLoader.createColorInstance(
+                Color.Blue, metallic = 0.8f, roughness = 0.2f
+            ),
+            position = Position(x = 0.6f)
+        )
+        // Floor plane
+        PlaneNode(
+            engine,
+            size = Size(2f, 0f, 2f),
+            materialInstance = materialLoader.createColorInstance(
+                Color(0xFF4CAF50), metallic = 0f, roughness = 0.9f
+            ),
+            position = Position(y = -0.35f)
+        )
+    }
 }`,
     },
     "ar-tap-to-place": {
         id: "ar-tap-to-place",
         title: "AR Tap-to-Place",
         description: "AR scene where each tap places a GLB model on a detected surface. Placed models are pinch-to-scale and drag-to-rotate.",
+        tags: ["ar", "model", "anchor", "plane-detection", "placement", "gestures"],
         dependency: "io.github.sceneview:arsceneview:3.0.0",
         prompt: "Create an Android Compose screen called `TapToPlaceScreen` that opens the camera in AR mode. Show a plane detection grid. When the user taps a detected surface, place a 3D GLB model from assets/models/chair.glb at that point. The user should be able to pinch-to-scale and drag-to-rotate after placing. Multiple taps = multiple objects. Use SceneView `io.github.sceneview:arsceneview:3.0.0`.",
         code: `@Composable
@@ -79,6 +137,7 @@ fun TapToPlaceScreen() {
         id: "ar-placement-cursor",
         title: "AR Placement Cursor",
         description: "AR scene with a reticle that follows the surface at screen center. Tap to confirm placement.",
+        tags: ["ar", "model", "anchor", "plane-detection", "placement", "camera"],
         dependency: "io.github.sceneview:arsceneview:3.0.0",
         prompt: "Create an Android Compose AR screen called `ARCursorScreen`. Show a small reticle that snaps to the nearest detected surface at the center of the screen as the user moves the camera. When the user taps, place a GLB model from assets/models/object.glb at that position and hide the reticle. Use SceneView `io.github.sceneview:arsceneview:3.0.0`.",
         code: `@Composable
@@ -125,6 +184,7 @@ fun ARCursorScreen() {
         id: "ar-augmented-image",
         title: "AR Augmented Image",
         description: "Detects a reference image in the camera feed and overlays a 3D model above it.",
+        tags: ["ar", "model", "anchor", "image-tracking"],
         dependency: "io.github.sceneview:arsceneview:3.0.0",
         prompt: "Create an Android Compose AR screen called `AugmentedImageScreen` that detects a printed reference image (from R.drawable.target_image, physical width 15 cm) and places a 3D GLB model from assets/models/overlay.glb above it, scaled to match the image width. The model should disappear when the image is lost. Use SceneView `io.github.sceneview:arsceneview:3.0.0`.",
         code: `@Composable
@@ -167,6 +227,7 @@ fun AugmentedImageScreen() {
         id: "ar-face-filter",
         title: "AR Face Filter",
         description: "Front-camera AR that detects faces and renders a 3D mesh material over them.",
+        tags: ["ar", "face-tracking", "camera"],
         dependency: "io.github.sceneview:arsceneview:3.0.0",
         prompt: "Create an Android Compose AR screen called `FaceFilterScreen` using the front camera. Detect all visible faces and apply a custom material from assets/materials/face_mask.filamat to the face mesh. Use SceneView `io.github.sceneview:arsceneview:3.0.0` with `Session.Feature.FRONT_CAMERA` and `AugmentedFaceMode.MESH3D`.",
         code: `@Composable

package/dist/samples.test.js

@@ -0,0 +1,119 @@
+import { describe, it, expect } from "vitest";
+import { SAMPLES, SAMPLE_IDS, getSample } from "./samples.js";
+describe("SAMPLE_IDS", () => {
+    it("contains all 6 expected scenarios", () => {
+        expect(SAMPLE_IDS).toContain("model-viewer");
+        expect(SAMPLE_IDS).toContain("geometry-scene");
+        expect(SAMPLE_IDS).toContain("ar-tap-to-place");
+        expect(SAMPLE_IDS).toContain("ar-placement-cursor");
+        expect(SAMPLE_IDS).toContain("ar-augmented-image");
+        expect(SAMPLE_IDS).toContain("ar-face-filter");
+    });
+    it("SAMPLE_IDS matches keys of SAMPLES", () => {
+        expect(SAMPLE_IDS.sort()).toEqual(Object.keys(SAMPLES).sort());
+    });
+});
+describe("every sample", () => {
+    for (const id of SAMPLE_IDS) {
+        const sample = SAMPLES[id];
+        it(`${id}: has all required fields`, () => {
+            expect(sample.id).toBe(id);
+            expect(sample.title).toBeTruthy();
+            expect(sample.description).toBeTruthy();
+            expect(sample.tags.length).toBeGreaterThan(0);
+            expect(sample.dependency).toMatch(/^io\.github\.sceneview:/);
+            expect(sample.prompt).toBeTruthy();
+            expect(sample.code).toBeTruthy();
+        });
+        it(`${id}: code is non-empty Kotlin`, () => {
+            expect(sample.code).toContain("@Composable");
+            expect(sample.code).toContain("fun ");
+        });
+        it(`${id}: dependency is a valid sceneview artifact`, () => {
+            expect(["io.github.sceneview:sceneview:3.0.0", "io.github.sceneview:arsceneview:3.0.0"]).toContain(sample.dependency);
+        });
+    }
+});
+describe("AR samples", () => {
+    const arIds = SAMPLE_IDS.filter((id) => SAMPLES[id].tags.includes("ar"));
+    it("all AR samples use arsceneview dependency", () => {
+        for (const id of arIds) {
+            expect(SAMPLES[id].dependency).toBe("io.github.sceneview:arsceneview:3.0.0");
+        }
+    });
+    it("all AR samples contain ARScene in code", () => {
+        for (const id of arIds) {
+            expect(SAMPLES[id].code).toContain("ARScene");
+        }
+    });
+    it("all AR samples have the 'ar' tag", () => {
+        for (const id of arIds) {
+            expect(SAMPLES[id].tags).toContain("ar");
+        }
+    });
+});
+describe("3D samples", () => {
+    const d3Ids = SAMPLE_IDS.filter((id) => SAMPLES[id].tags.includes("3d"));
+    it("all 3D samples use sceneview dependency", () => {
+        for (const id of d3Ids) {
+            expect(SAMPLES[id].dependency).toBe("io.github.sceneview:sceneview:3.0.0");
+        }
+    });
+    it("all 3D samples contain Scene in code", () => {
+        for (const id of d3Ids) {
+            expect(SAMPLES[id].code).toContain("Scene(");
+        }
+    });
+});
+describe("getSample", () => {
+    it("returns the correct sample by ID", () => {
+        const s = getSample("model-viewer");
+        expect(s).toBeDefined();
+        expect(s.id).toBe("model-viewer");
+        expect(s.title).toBe("3D Model Viewer");
+    });
+    it("returns undefined for an unknown ID", () => {
+        expect(getSample("nonexistent-scenario")).toBeUndefined();
+    });
+    it("returns all samples without undefined", () => {
+        for (const id of SAMPLE_IDS) {
+            expect(getSample(id)).toBeDefined();
+        }
+    });
+});
+describe("tag filtering (simulating list_samples tool)", () => {
+    const filterByTag = (tag) => Object.values(SAMPLES).filter((s) => s.tags.includes(tag));
+    it("tag 'ar' returns only AR samples", () => {
+        const results = filterByTag("ar");
+        expect(results.length).toBeGreaterThan(0);
+        results.forEach((s) => expect(s.tags).toContain("ar"));
+    });
+    it("tag '3d' returns only 3D samples", () => {
+        const results = filterByTag("3d");
+        expect(results.length).toBeGreaterThan(0);
+        results.forEach((s) => expect(s.tags).toContain("3d"));
+    });
+    it("tag 'face-tracking' returns only the face filter sample", () => {
+        const results = filterByTag("face-tracking");
+        expect(results).toHaveLength(1);
+        expect(results[0].id).toBe("ar-face-filter");
+    });
+    it("tag 'image-tracking' returns only augmented image sample", () => {
+        const results = filterByTag("image-tracking");
+        expect(results).toHaveLength(1);
+        expect(results[0].id).toBe("ar-augmented-image");
+    });
+    it("tag 'geometry' returns only geometry scene", () => {
+        const results = filterByTag("geometry");
+        expect(results).toHaveLength(1);
+        expect(results[0].id).toBe("geometry-scene");
+    });
+    it("tag 'anchor' returns AR samples that use anchors", () => {
+        const results = filterByTag("anchor");
+        expect(results.length).toBeGreaterThan(0);
+        results.forEach((s) => expect(s.tags).toContain("anchor"));
+    });
+    it("unknown tag returns empty array", () => {
+        expect(filterByTag("nonexistent-tag")).toHaveLength(0);
+    });
+});