sceneview-mcp 3.5.5 → 3.6.1

package/dist/index.js

@@ -39,7 +39,7 @@ catch {
     API_DOCS = "SceneView API docs not found. Run `npm run prepare` to bundle llms.txt.";
 }
 const NODE_SECTIONS = parseNodeSections(API_DOCS);
-const server = new Server({ name: "sceneview-mcp", version: "3.5.5" }, { capabilities: { resources: {}, tools: {} } });
+const server = new Server({ name: "sceneview-mcp", version: "3.6.1" }, { capabilities: { resources: {}, tools: {} } });
 // ─── Resources ───────────────────────────────────────────────────────────────
 server.setRequestHandler(ListResourcesRequestSchema, async () => ({
     resources: [
@@ -514,7 +514,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ? [
                     `**SPM dependency:**`,
                     `\`\`\`swift`,
-                    `.package(url: "${sample.spmDependency ?? sample.dependency}", from: "3.6.0")`,
+                    `.package(url: "${sample.spmDependency ?? sample.dependency}", from: "3.6.1")`,
                     `\`\`\``,
                 ]
                 : [
@@ -732,7 +732,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 `    name: "MyApp",`,
                                 `    platforms: [.iOS(.v17), .macOS(.v14), .visionOS(.v1)],`,
                                 `    dependencies: [`,
-                                `        .package(url: "https://github.com/sceneview/sceneview", from: "3.6.0")`,
+                                `        .package(url: "https://github.com/sceneview/sceneview", from: "3.6.1")`,
                                 `    ],`,
                                 `    targets: [`,
                                 `        .executableTarget(`,
@@ -803,7 +803,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 `### 1. Add SPM Dependency`,
                                 ``,
                                 `\`\`\`swift`,
-                                `.package(url: "https://github.com/sceneview/sceneview", from: "3.6.0")`,
+                                `.package(url: "https://github.com/sceneview/sceneview", from: "3.6.1")`,
                                 `\`\`\``,
                                 ``,
                                 `### 2. Minimum Platform`,
@@ -1083,15 +1083,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         // ── list_platforms ────────────────────────────────────────────────────────
         case "list_platforms": {
             const platforms = [
-                { platform: "Android", renderer: "Filament", framework: "Jetpack Compose", status: "Stable", version: "3.6.0", dependency: "io.github.sceneview:sceneview:3.6.0", features: ["3D", "AR (ARCore)", "Model loading (GLB/glTF)", "Geometry nodes", "Physics", "Gestures"] },
-                { platform: "Android TV", renderer: "Filament", framework: "Compose TV", status: "Alpha", version: "3.6.0", dependency: "io.github.sceneview:sceneview:3.6.0", features: ["3D", "D-pad controls", "Auto-rotation", "Model loading"] },
+                { platform: "Android", renderer: "Filament", framework: "Jetpack Compose", status: "Stable", version: "3.6.1", dependency: "io.github.sceneview:sceneview:3.6.0", features: ["3D", "AR (ARCore)", "Model loading (GLB/glTF)", "Geometry nodes", "Physics", "Gestures"] },
+                { platform: "Android TV", renderer: "Filament", framework: "Compose TV", status: "Alpha", version: "3.6.1", dependency: "io.github.sceneview:sceneview:3.6.0", features: ["3D", "D-pad controls", "Auto-rotation", "Model loading"] },
                 { platform: "Android XR", renderer: "Jetpack XR SceneCore", framework: "Compose XR", status: "Planned", version: "-", dependency: "-", features: ["Spatial computing", "Hand tracking", "Passthrough"] },
-                { platform: "iOS", renderer: "RealityKit", framework: "SwiftUI", status: "Alpha", version: "3.6.0", dependency: "SceneViewSwift (SPM)", features: ["3D", "AR (ARKit)", "16 node types", "USDZ models"] },
-                { platform: "macOS", renderer: "RealityKit", framework: "SwiftUI", status: "Alpha", version: "3.6.0", dependency: "SceneViewSwift (SPM)", features: ["3D", "Orbit camera", "USDZ models"] },
-                { platform: "visionOS", renderer: "RealityKit", framework: "SwiftUI", status: "Alpha", version: "3.6.0", dependency: "SceneViewSwift (SPM)", features: ["3D", "Immersive spaces", "Hand tracking (planned)"] },
-                { platform: "Web", renderer: "Filament.js (WASM)", framework: "Kotlin/JS", status: "Alpha", version: "3.6.0", dependency: "@sceneview/sceneview-web", features: ["3D", "WebXR AR/VR", "GLB models", "WebGL2"] },
-                { platform: "Desktop", renderer: "Software / Filament JNI", framework: "Compose Desktop", status: "Alpha", version: "3.6.0", dependency: "sceneview-desktop (local)", features: ["3D", "Software renderer", "Wireframe"] },
-                { platform: "Flutter", renderer: "Filament / RealityKit", framework: "PlatformView", status: "Alpha", version: "3.6.0", dependency: "flutter pub: sceneview", features: ["3D", "AR", "Android + iOS bridge"] },
+                { platform: "iOS", renderer: "RealityKit", framework: "SwiftUI", status: "Alpha", version: "3.6.1", dependency: "SceneViewSwift (SPM)", features: ["3D", "AR (ARKit)", "16 node types", "USDZ models"] },
+                { platform: "macOS", renderer: "RealityKit", framework: "SwiftUI", status: "Alpha", version: "3.6.1", dependency: "SceneViewSwift (SPM)", features: ["3D", "Orbit camera", "USDZ models"] },
+                { platform: "visionOS", renderer: "RealityKit", framework: "SwiftUI", status: "Alpha", version: "3.6.1", dependency: "SceneViewSwift (SPM)", features: ["3D", "Immersive spaces", "Hand tracking (planned)"] },
+                { platform: "Web", renderer: "Filament.js (WASM)", framework: "Kotlin/JS", status: "Alpha", version: "3.6.1", dependency: "@sceneview/sceneview-web", features: ["3D", "WebXR AR/VR", "GLB models", "WebGL2"] },
+                { platform: "Desktop", renderer: "Software / Filament JNI", framework: "Compose Desktop", status: "Alpha", version: "3.6.1", dependency: "sceneview-desktop (local)", features: ["3D", "Software renderer", "Wireframe"] },
+                { platform: "Flutter", renderer: "Filament / RealityKit", framework: "PlatformView", status: "Alpha", version: "3.6.1", dependency: "flutter pub: sceneview", features: ["3D", "AR", "Android + iOS bridge"] },
             ];
             const lines = [
                 "## SceneView Supported Platforms\n",

package/llms.txt

@@ -3,8 +3,8 @@
 SceneView is a declarative 3D and AR SDK for Android (Jetpack Compose, Filament, ARCore) and Apple platforms — iOS, macOS, visionOS (SwiftUI, RealityKit, ARKit) — with shared core logic via Kotlin Multiplatform. Each platform uses its native renderer: Filament on Android, RealityKit on Apple.
 
 **Android — Maven artifacts (version 3.6.0):**
-- 3D only: `io.github.sceneview:sceneview:3.6.0`
-- AR + 3D: `io.github.sceneview:arsceneview:3.6.0`
+- 3D only: `io.github.sceneview:sceneview:3.6.1`
+- AR + 3D: `io.github.sceneview:arsceneview:3.6.1`
 
 **Apple (iOS 17+ / macOS 14+ / visionOS 1+) — Swift Package:**
 - `https://github.com/sceneview/sceneview-swift.git` (from: "3.6.0")
@@ -18,8 +18,8 @@ SceneView is a declarative 3D and AR SDK for Android (Jetpack Compose, Filament,
 ### build.gradle (app module)
 ```kotlin
 dependencies {
-    implementation("io.github.sceneview:sceneview:3.6.0")   // 3D only
-    implementation("io.github.sceneview:arsceneview:3.6.0") // AR (includes sceneview)
+    implementation("io.github.sceneview:sceneview:3.6.1")   // 3D only
+    implementation("io.github.sceneview:arsceneview:3.6.1") // AR (includes sceneview)
 }
 ```
 
@@ -836,10 +836,13 @@ class ModelLoader(engine: Engine, context: Context) {
     fun createModelInstance(buffer: Buffer): ModelInstance
     fun createModelInstance(@RawRes rawResId: Int): ModelInstance
     fun createModelInstance(file: File): ModelInstance
-    fun createModel(assetFileLocation: String): Model
-    fun createModel(buffer: Buffer): Model
-    fun createModel(@RawRes rawResId: Int): Model
-    fun createModel(file: File): Model
+
+    // releaseSourceData (default true): frees the raw buffer after Filament parses the model.
+    // Set to false only when you need to re-instantiate the same model multiple times.
+    fun createModel(assetFileLocation: String, releaseSourceData: Boolean = true): Model
+    fun createModel(buffer: Buffer, releaseSourceData: Boolean = true): Model
+    fun createModel(@RawRes rawResId: Int, releaseSourceData: Boolean = true): Model
+    fun createModel(file: File, releaseSourceData: Boolean = true): Model
 
     // Async — safe from any thread
     suspend fun loadModel(fileLocation: String): Model?
@@ -1369,6 +1372,113 @@ fun ARFaceTracking() {
 
 ---
 
+## Android Advanced APIs
+
+### SceneRenderer
+
+`SceneRenderer` encapsulates the Filament surface lifecycle and render-frame pipeline. Both `SceneView` (3D) and `ARSceneView` (AR) share the same surface management and frame-presentation code through this class.
+
+```kotlin
+class SceneRenderer(engine: Engine, view: View, renderer: Renderer) {
+    val isAttached: Boolean               // true when a swap chain is ready
+    var onSurfaceResized: ((width: Int, height: Int) -> Unit)?
+    var onSurfaceReady: ((viewHeight: () -> Int) -> Unit)?
+    var onSurfaceDestroyed: (() -> Unit)?
+
+    fun attachToSurfaceView(surfaceView: SurfaceView, isOpaque: Boolean, context: Context, display: Display, onTouch: ((MotionEvent) -> Unit)? = null)
+    fun attachToTextureView(textureView: TextureView, isOpaque: Boolean, context: Context, display: Display, onTouch: ((MotionEvent) -> Unit)? = null)
+    fun renderFrame(frameTimeNanos: Long, onBeforeRender: () -> Unit)
+    fun applyResize(width: Int, height: Int)
+    fun destroy()
+}
+```
+
+Typical composable usage:
+```kotlin
+val sceneRenderer = remember(engine, renderer) { SceneRenderer(engine, view, renderer) }
+DisposableEffect(sceneRenderer) { onDispose { sceneRenderer.destroy() } }
+```
+
+### NodeGestureDelegate
+
+`NodeGestureDelegate` handles all gesture detection and callback logic for a `Node`. Gesture callbacks (e.g. `node.onTouch`, `node.onSingleTapConfirmed`) are forwarded through this delegate. Access it directly when you need to batch-configure callbacks or inspect `editingTransforms`:
+
+```kotlin
+// Preferred — set callbacks directly on the node (delegates internally):
+node.onSingleTapConfirmed = { e -> true }
+node.onMove = { detector, e, worldPosition -> true }
+
+// Advanced — access the delegate directly:
+node.gestureDelegate.editingTransforms  // Set<KProperty1<Node, Any>> currently being edited
+node.gestureDelegate.onEditingChanged = { transforms -> /* transforms changed */ }
+```
+
+Available callbacks on `NodeGestureDelegate` (and mirrored on `Node`):
+`onTouch`, `onDown`, `onShowPress`, `onSingleTapUp`, `onScroll`, `onLongPress`, `onFling`,
+`onSingleTapConfirmed`, `onDoubleTap`, `onDoubleTapEvent`, `onContextClick`,
+`onMoveBegin`, `onMove`, `onMoveEnd`,
+`onRotateBegin`, `onRotate`, `onRotateEnd`,
+`onScaleBegin`, `onScale`, `onScaleEnd`,
+`onEditingChanged`, `editingTransforms`.
+
+### NodeAnimationDelegate
+
+`NodeAnimationDelegate` handles smooth (interpolated) transform animation for a `Node`. Access via `node.animationDelegate`:
+
+```kotlin
+// Preferred — use Node property aliases:
+node.isSmoothTransformEnabled = true
+node.smoothTransformSpeed = 5.0f      // higher = faster convergence
+node.smoothTransform = targetTransform
+node.onSmoothEnd = { n -> /* reached target */ }
+
+// Advanced — access the delegate directly:
+node.animationDelegate.smoothTransform = targetTransform
+```
+
+The per-frame interpolation uses slerp. Once the transform reaches the target (within 0.001 tolerance), `onSmoothEnd` fires and the animation clears.
+
+### NodeState
+
+`NodeState` is an immutable snapshot of a `Node`'s observable state. Use it for ViewModel-driven UI or save/restore patterns:
+
+```kotlin
+data class NodeState(
+    val position: Position = Position(),
+    val quaternion: Quaternion = Quaternion(),
+    val scale: Scale = Scale(1f),
+    val isVisible: Boolean = true,
+    val isEditable: Boolean = false,
+    val isTouchable: Boolean = true
+)
+
+// Capture current state
+val state: NodeState = node.toState()
+
+// Restore state
+node.applyState(state)
+```
+
+### ARPermissionHandler
+
+`ARPermissionHandler` abstracts camera permission and ARCore availability checks away from `ComponentActivity`, enabling testability:
+
+```kotlin
+interface ARPermissionHandler {
+    fun hasCameraPermission(): Boolean
+    fun requestCameraPermission(onResult: (granted: Boolean) -> Unit)
+    fun shouldShowPermissionRationale(): Boolean
+    fun openAppSettings()
+    fun checkARCoreAvailability(): ArCoreApk.Availability
+    fun requestARCoreInstall(userRequestedInstall: Boolean): Boolean
+}
+
+// Production implementation backed by ComponentActivity:
+class ActivityARPermissionHandler(activity: ComponentActivity) : ARPermissionHandler
+```
+
+---
+
 ## sceneview-core (KMP)
 
 `sceneview-core` is a Kotlin Multiplatform module containing platform-independent logic shared between Android and iOS. It targets `jvm("android")`, `iosArm64`, `iosSimulatorArm64`, and `iosX64`. It depends on `dev.romainguy:kotlin-math:1.6.0` (exposed as `api`).
@@ -1494,6 +1604,19 @@ generateShape(polygonPath: List<Float2>, polygonHoles: List<Int>, delaunayPoints
 | `CollisionShape` | Base class — `rayIntersection(ray, rayHit): Boolean` |
 | `Intersections` | Static tests: sphere-sphere, box-box, ray-sphere, ray-box, ray-plane |
 
+The Android `CollisionSystem` (in `sceneview` module) exposes `hitTest()` for screen-space and ray-based queries:
+```kotlin
+// Preferred API
+collisionSystem.hitTest(motionEvent): List<HitResult>   // from touch event
+collisionSystem.hitTest(xPx, yPx): List<HitResult>      // screen pixels
+collisionSystem.hitTest(viewPosition: Float2): List<HitResult>  // normalized [0..1]
+collisionSystem.hitTest(ray: Ray): List<HitResult>       // explicit ray
+
+// @Deprecated — use hitTest() instead
+@Deprecated collisionSystem.raycast(ray): HitResult?         // → hitTest(ray).firstOrNull()
+@Deprecated collisionSystem.raycastAll(ray): List<HitResult> // → hitTest(ray)
+```
+
 ### Triangulation
 
 | Class | Purpose |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sceneview-mcp",
-  "version": "3.5.5",
+  "version": "3.6.1",
   "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": [