sceneview-mcp 4.0.14 → 4.0.15

package/dist/generated/version.js

@@ -4,5 +4,5 @@
 // build time so the MCP server, telemetry, and the install-snippet
 // generators all report the actually-published versions instead of
 // stale hardcoded constants. See #941.
-export const PACKAGE_VERSION = "4.0.14";
-export const LATEST_SCENEVIEW_RELEASE = "4.22.0";
+export const PACKAGE_VERSION = "4.0.15";
+export const LATEST_SCENEVIEW_RELEASE = "4.25.0";

package/dist/platform-setup.js

@@ -414,18 +414,14 @@ SceneView Flutter uses **PlatformView** to embed native SceneView (Android: Fila
 
 ### 1. Dependencies
 
-> **Note:** the 4.0 line of \`sceneview_flutter\` is not yet on pub.dev
-> (registry still holds an unrelated 0.0.1 demo) — see #923. Use the
-> git dependency snippet below for now.
+> **Note:** the plugin is published on pub.dev as \`flutter_sceneview\`
+> (the pub.dev names \`sceneview\` and \`sceneview_flutter\` are unrelated
+> third-party uploads — do not use them).
 
 \`\`\`yaml
 # pubspec.yaml
 dependencies:
-  sceneview_flutter:
-    git:
-      url: https://github.com/sceneview/sceneview
-      path: flutter/sceneview_flutter
-      ref: v${LATEST_SCENEVIEW_RELEASE}
+  flutter_sceneview: ^${LATEST_SCENEVIEW_RELEASE}
 \`\`\`
 
 ### 2. Android Setup
@@ -483,13 +479,9 @@ const FLUTTER_AR = `## SceneView Flutter — AR Setup
 ### 1. Dependencies
 
 \`\`\`yaml
-# pub.dev publish for 4.x is pending — see #923. Use the git ref:
+# pubspec.yaml — published on pub.dev (the names sceneview / sceneview_flutter are unrelated third-party uploads)
 dependencies:
-  sceneview_flutter:
-    git:
-      url: https://github.com/sceneview/sceneview
-      path: flutter/sceneview_flutter
-      ref: v${LATEST_SCENEVIEW_RELEASE}
+  flutter_sceneview: ^${LATEST_SCENEVIEW_RELEASE}
 \`\`\`
 
 ### 2. Android Manifest

package/dist/symbols.js

@@ -0,0 +1,204 @@
+/**
+ * Symbol-existence lookups over the generated public-API index (#2760).
+ *
+ * The index (`src/generated/symbols.ts`) is parsed from the committed
+ * binary-compatibility `.api` dumps at build time — see
+ * `scripts/generate-symbols.js` for the full provenance chain. Everything
+ * here answers one question for the validator: "does this identifier exist
+ * in the real Android/KMP SceneView API?", with edit-distance suggestions
+ * when it doesn't.
+ *
+ * Scope, stated honestly: the dumps cover `sceneview`, `arsceneview` and
+ * `sceneview-core` (Android/KMP). SceneViewSwift and sceneview-web have no
+ * committed dump, so Swift/Web snippets are NOT symbol-checked.
+ */
+import { SYMBOLS } from "./generated/symbols.js";
+export const SCENEVIEW_NAMESPACE = "io.github.sceneview";
+// ─── Lazily-built lookup sets ────────────────────────────────────────────────
+let typeNamesCache = null;
+let classBySimpleNameCache = null;
+/**
+ * Every PascalCase identifier a Kotlin user can legitimately reference as a
+ * type or declarative factory:
+ *  - class simple names (`ModelNode`, `WallPlacement`, …),
+ *  - PascalCase top-level functions — the composables (`SceneView`,
+ *    `ARSceneView`, `WallPlacementScene`, `DynamicSkyNode`, …),
+ *  - PascalCase members of the `*Scope` classes — the declarative node
+ *    factories (`SceneScope.ModelNode`, `ARSceneScope.…`).
+ */
+export function knownTypeNames() {
+    if (typeNamesCache)
+        return typeNamesCache;
+    const names = new Set();
+    for (const fqcn of Object.keys(SYMBOLS.classes)) {
+        const simple = fqcn.slice(fqcn.lastIndexOf(".") + 1);
+        if (/^[A-Z]/.test(simple))
+            names.add(simple);
+    }
+    for (const name of Object.keys(SYMBOLS.topLevel)) {
+        if (/^[A-Z]/.test(name))
+            names.add(name);
+    }
+    for (const [fqcn, entry] of Object.entries(SYMBOLS.classes)) {
+        if (!fqcn.endsWith("Scope"))
+            continue;
+        for (const member of entry.members) {
+            if (/^[A-Z]/.test(member))
+                names.add(member);
+        }
+    }
+    typeNamesCache = names;
+    return names;
+}
+/** Class simple name → the FQCNs that declare it (usually exactly one). */
+function classBySimpleName() {
+    if (classBySimpleNameCache)
+        return classBySimpleNameCache;
+    const map = new Map();
+    for (const fqcn of Object.keys(SYMBOLS.classes)) {
+        const simple = fqcn.slice(fqcn.lastIndexOf(".") + 1);
+        const list = map.get(simple);
+        if (list)
+            list.push(fqcn);
+        else
+            map.set(simple, [fqcn]);
+    }
+    classBySimpleNameCache = map;
+    return map;
+}
+export function isKnownTypeName(name) {
+    return knownTypeNames().has(name);
+}
+/** Top-level function (any case) — composables and extension helpers. */
+export function isKnownTopLevelFunction(name) {
+    return name in SYMBOLS.topLevel;
+}
+/** Every real `remember*` composable helper — suggestion pool for typos. */
+export function rememberHelperNames() {
+    return Object.keys(SYMBOLS.topLevel).filter((name) => name.startsWith("remember"));
+}
+/**
+ * Resolve an `io.github.sceneview.*` import target.
+ *
+ * Returns "class" for an exact class FQCN, "package" for a package that
+ * exists (covers `import io.github.sceneview.node.*`), "member" for a
+ * `Class.member` or package-level function import, and null when nothing
+ * in the index matches. Callers must only pass SceneView-namespace paths —
+ * other namespaces are out of index scope.
+ */
+export function resolveImport(path) {
+    if (path in SYMBOLS.classes)
+        return "class";
+    if (SYMBOLS.packages.includes(path))
+        return "package";
+    const lastDot = path.lastIndexOf(".");
+    if (lastDot === -1)
+        return null;
+    const parent = path.slice(0, lastDot);
+    const leaf = path.slice(lastDot + 1);
+    // `import io.github.sceneview.ar.rememberARCameraStream` — a top-level
+    // function imported from a package.
+    if (SYMBOLS.packages.includes(parent) && leaf in SYMBOLS.topLevel) {
+        return "member";
+    }
+    // A nested class member — accept when the parent class exists and
+    // declares it.
+    const parentClass = SYMBOLS.classes[parent];
+    if (parentClass?.members.includes(leaf))
+        return "member";
+    // `import io.github.sceneview.node.ModelNode.Companion` — the generator
+    // folds companion members into the host class and drops the `.Companion`
+    // entry, so resolve the companion itself through its host.
+    if (leaf === "Companion" && parent in SYMBOLS.classes)
+        return "member";
+    return null;
+}
+/** Union of member/property names declared by classes with this simple name. */
+export function membersOfClass(simpleName) {
+    const fqcns = classBySimpleName().get(simpleName);
+    if (!fqcns)
+        return null;
+    const members = new Set();
+    for (const fqcn of fqcns) {
+        for (const m of SYMBOLS.classes[fqcn].members)
+            members.add(m);
+    }
+    return members;
+}
+// ─── Edit-distance suggestions ───────────────────────────────────────────────
+/** Classic Levenshtein with a band cutoff — returns Infinity past `max`. */
+export function editDistance(a, b, max) {
+    if (Math.abs(a.length - b.length) > max)
+        return Number.POSITIVE_INFINITY;
+    const la = a.length;
+    const lb = b.length;
+    let prev = Array.from({ length: lb + 1 }, (_, i) => i);
+    let curr = new Array(lb + 1);
+    for (let i = 1; i <= la; i++) {
+        curr[0] = i;
+        let rowMin = i;
+        for (let j = 1; j <= lb; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+            if (curr[j] < rowMin)
+                rowMin = curr[j];
+        }
+        if (rowMin > max)
+            return Number.POSITIVE_INFINITY;
+        [prev, curr] = [curr, prev];
+    }
+    return prev[lb] <= max ? prev[lb] : Number.POSITIVE_INFINITY;
+}
+/** camelCase identifier → lowercased token set (`loadModelAsync` → load,model,async). */
+function camelTokens(name) {
+    return new Set(name
+        .split(/(?=[A-Z])/)
+        .map((t) => t.toLowerCase())
+        .filter((t) => t.length > 0));
+}
+/** Jaccard similarity of the camelCase token sets of two identifiers. */
+export function tokenSimilarity(a, b) {
+    const ta = camelTokens(a);
+    const tb = camelTokens(b);
+    let inter = 0;
+    for (const t of ta)
+        if (tb.has(t))
+            inter++;
+    const union = ta.size + tb.size - inter;
+    return union === 0 ? 0 : inter / union;
+}
+/**
+ * Closest candidates to `name`, nearest first, by a hybrid metric:
+ *  - Levenshtein within a length-scaled band (2 for short names, 3 for long)
+ *    catches character typos (`ModellNode` → `ModelNode`);
+ *  - camelCase token overlap (Jaccard ≥ 0.5) catches structural
+ *    hallucinations that raw edit distance can't reach —
+ *    `createModelInstanceAsync` → `loadModelInstanceAsync` is distance 5,
+ *    but shares 3 of 5 camelCase tokens.
+ * Token matches are scored `10 × (1 − similarity)` so an exact-ish edit
+ * match always outranks a merely structural one.
+ */
+export function suggestClosest(name, candidates, limit = 3) {
+    const max = name.length < 12 ? 2 : 3;
+    const lower = name.toLowerCase();
+    const scored = [];
+    for (const candidate of candidates) {
+        const d = editDistance(lower, candidate.toLowerCase(), max);
+        if (d !== Number.POSITIVE_INFINITY) {
+            scored.push([candidate, d]);
+            continue;
+        }
+        const similarity = tokenSimilarity(name, candidate);
+        if (similarity >= 0.5)
+            scored.push([candidate, 10 * (1 - similarity)]);
+    }
+    scored.sort((x, y) => x[1] - y[1] || x[0].localeCompare(y[0]));
+    return scored.slice(0, limit).map(([candidate]) => candidate);
+}
+/** Human-readable " Did you mean …?" suffix, or "" when nothing is close. */
+export function didYouMean(name, candidates) {
+    const close = suggestClosest(name, candidates);
+    if (close.length === 0)
+        return "";
+    return ` Did you mean ${close.map((c) => `\`${c}\``).join(", ")}?`;
+}

package/dist/tools/definitions.js

@@ -72,7 +72,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: "validate_code",
-        description: "Checks a Kotlin or Swift SceneView snippet for common mistakes. For Kotlin: threading violations, wrong destroy order, missing null-checks, LightNode trailing-lambda bug, deprecated 2.x APIs. For Swift: missing @MainActor, async/await patterns, missing imports, RealityKit mistakes. Language is auto-detected. Always call this before presenting generated SceneView code to the user.",
+        description: "Checks a Kotlin or Swift SceneView snippet for common mistakes. For Kotlin: symbol existence against the real public API (unknown imports, made-up node types, nonexistent loader methods — with did-you-mean suggestions), threading violations, wrong destroy order, missing null-checks, LightNode trailing-lambda bug, deprecated 2.x APIs. For Swift: missing @MainActor, async/await patterns, missing imports, RealityKit mistakes. Language is auto-detected. Always call this before presenting generated SceneView code to the user.",
         inputSchema: {
             type: "object",
             properties: {

package/dist/tools/handler.js

@@ -697,7 +697,7 @@ export async function dispatchTool(toolName, args, _ctx = {}) {
                 { platform: "visionOS", renderer: "RealityKit", framework: "SwiftUI", status: "Alpha", version: LATEST_SCENEVIEW_RELEASE, dependency: "SceneViewSwift (SPM)", features: ["3D", "Immersive spaces", "Hand tracking (planned)"] },
                 { platform: "Web", renderer: "Filament.js (WASM)", framework: "Kotlin/JS", status: "Alpha", version: LATEST_SCENEVIEW_RELEASE, dependency: "sceneview-web (npm)", features: ["3D", "WebXR AR/VR", "GLB models", "WebGL2"] },
                 { platform: "Desktop", renderer: "Software / Filament JNI", framework: "Compose Desktop", status: "Alpha", version: LATEST_SCENEVIEW_RELEASE, dependency: "sceneview-desktop (local)", features: ["3D", "Software renderer", "Wireframe"] },
-                { platform: "Flutter", renderer: "Filament / RealityKit", framework: "PlatformView", status: "Alpha", version: LATEST_SCENEVIEW_RELEASE, dependency: "flutter pub: sceneview_flutter (git ref)", features: ["3D", "AR", "Android + iOS bridge"] },
+                { platform: "Flutter", renderer: "Filament / RealityKit", framework: "PlatformView", status: "Alpha", version: LATEST_SCENEVIEW_RELEASE, dependency: "flutter pub: flutter_sceneview (git ref until first publish, #2735)", features: ["3D", "AR", "Android + iOS bridge"] },
             ];
             const lines = [
                 "## SceneView Supported Platforms\n",

package/dist/validator.js

@@ -1,8 +1,20 @@
+import { didYouMean, isKnownTopLevelFunction, isKnownTypeName, knownTypeNames, membersOfClass, rememberHelperNames, resolveImport, } from "./symbols.js";
 function findLines(lines, pattern) {
     return lines
         .map((l, i) => (pattern.test(l) ? i + 1 : -1))
         .filter((n) => n !== -1);
 }
+// Symbols the snippet declares itself (`fun MyShowcaseScene(…)`, `class ShelfNode(…) :
+// Node(engine)`) exist by definition — they are the caller's own wrappers, not calls into
+// SceneView, and the SDK's naming idiom (`WallPlacementScene`, `PhysicsNode`) makes such
+// suffixes natural. The optional `<…>` skips a generic parameter list before the name.
+function locallyDeclaredNames(code) {
+    const names = new Set();
+    for (const m of code.matchAll(/\b(?:fun|class|interface|object)\s+(?:<[^>]*>\s+)?(\w+)/g)) {
+        names.add(m[1]);
+    }
+    return names;
+}
 const RULES = [
     // ─── Threading ────────────────────────────────────────────────────────────
     {
@@ -450,6 +462,193 @@ const RULES = [
             return issues;
         },
     },
+    // ─── Symbol existence (#2760) — backed by the generated .api index ────────
+    //
+    // These rules answer "does this API actually exist?", the #1 failure mode
+    // of AI-generated snippets. The index covers the Android/KMP surface
+    // (sceneview, arsceneview, sceneview-core) — see `symbols.ts`. Each rule is
+    // deliberately narrow so its false-positive space is ~zero.
+    {
+        // `import io.github.sceneview.…` that resolves to nothing. Our own
+        // namespace: nothing outside the index can legitimately live there.
+        // Known tolerated false NEGATIVE: aliased imports (`import … as MN`)
+        // don't match the end-of-line anchor and are silently skipped — an
+        // unchecked alias can never become a false positive.
+        id: "symbols/unknown-import",
+        severity: "error",
+        check(code, lines) {
+            const issues = [];
+            const importRe = /^\s*import\s+(io\.github\.sceneview(?:\.\w+)*)(\.\*)?\s*$/;
+            lines.forEach((content, i) => {
+                const m = importRe.exec(content);
+                if (!m)
+                    return;
+                const path = m[1];
+                const isWildcard = m[2] !== undefined;
+                const resolved = resolveImport(path);
+                const ok = isWildcard ? resolved === "package" : resolved !== null;
+                if (ok)
+                    return;
+                const leaf = path.slice(path.lastIndexOf(".") + 1);
+                const suggestion = didYouMean(leaf, knownTypeNames());
+                issues.push({
+                    severity: "error",
+                    rule: "symbols/unknown-import",
+                    message: `\`import ${path}${isWildcard ? ".*" : ""}\` does not exist in the SceneView public API.${suggestion} Check the class name and package against \`llms.txt\`.`,
+                    line: i + 1,
+                });
+            });
+            return issues;
+        },
+    },
+    {
+        // A made-up `…Node(` / `…Node {` / `…Scene(` type or declarative factory.
+        id: "symbols/unknown-type",
+        severity: "error",
+        check(code, lines) {
+            const issues = [];
+            // Names already handled (with a better, migration-specific message) by
+            // `migration/old-api` — don't double-report them here.
+            const migrationCovered = new Set([
+                "Scene",
+                "ARScene",
+                "ArSceneView",
+                "PlacementNode",
+                "TransformableNode",
+            ]);
+            const callRe = /\b([A-Z]\w*(?:Node|Scene))\s*[({]/g;
+            const localNames = locallyDeclaredNames(code);
+            const seen = new Set();
+            for (const match of code.matchAll(callRe)) {
+                const name = match[1];
+                if (seen.has(name))
+                    continue;
+                seen.add(name);
+                if (migrationCovered.has(name))
+                    continue;
+                if (localNames.has(name))
+                    continue;
+                if (isKnownTypeName(name))
+                    continue;
+                const suggestion = didYouMean(name, knownTypeNames());
+                findLines(lines, new RegExp(`\\b${name}\\s*[({]`)).forEach((line) => issues.push({
+                    severity: "error",
+                    rule: "symbols/unknown-type",
+                    message: `\`${name}\` does not exist in the SceneView public API.${suggestion} Node types and declarative factories are listed in \`llms.txt\`.`,
+                    line,
+                }));
+            }
+            return issues;
+        },
+    },
+    {
+        // A nonexistent member called on a canonically-named loader variable —
+        // e.g. `modelLoader.createModelInstanceAsync(...)` (the real API is
+        // `loadModelInstanceAsync`). Heuristic on the receiver NAME, which the
+        // docs and every sample use consistently.
+        id: "symbols/unknown-member",
+        severity: "error",
+        check(code, lines) {
+            const issues = [];
+            const receivers = {
+                modelLoader: "ModelLoader",
+                materialLoader: "MaterialLoader",
+                environmentLoader: "EnvironmentLoader",
+            };
+            // Kotlin stdlib scope/extension functions callable on any receiver.
+            const stdlib = new Set([
+                "apply",
+                "also",
+                "let",
+                "run",
+                "takeIf",
+                "takeUnless",
+                "to",
+                "use",
+                "toString",
+            ]);
+            // A snippet may rebind a canonical name to its own type
+            // (`val modelLoader = MyRepository()`) — member-checking that variable
+            // against the SceneView loader would be a false positive
+            // (adversarial-review finding #3 on PR #2814). Keep checking only when
+            // the declaration is recognizably the real loader: a `remember<Class>`
+            // call, a direct constructor, a `: <Class>` type annotation, or a
+            // `.<receiver>` property access — or when there is no local
+            // declaration at all (the scope provides it, the canonical case).
+            const rebound = new Set();
+            for (const [receiver, className] of Object.entries(receivers)) {
+                const decl = new RegExp(`\\b(?:val|var)\\s+${receiver}\\s*(?::\\s*([^=\\n]+?))?\\s*=\\s*(.+)`).exec(code);
+                if (!decl)
+                    continue;
+                const [, typeAnnotation, rhs] = decl;
+                const looksReal = (typeAnnotation?.includes(className) ?? false) ||
+                    rhs.includes(`remember${className}`) ||
+                    rhs.includes(`${className}(`) ||
+                    rhs.trimEnd().endsWith(`.${receiver}`);
+                if (!looksReal)
+                    rebound.add(receiver);
+            }
+            const callRe = /\b(modelLoader|materialLoader|environmentLoader)\.(\w+)\s*\(/g;
+            const reported = new Set();
+            for (const match of code.matchAll(callRe)) {
+                const [, receiver, member] = match;
+                const key = `${receiver}.${member}`;
+                if (reported.has(key))
+                    continue;
+                reported.add(key);
+                if (rebound.has(receiver))
+                    continue;
+                if (stdlib.has(member))
+                    continue;
+                const members = membersOfClass(receivers[receiver]);
+                if (!members || members.has(member))
+                    continue;
+                const suggestion = didYouMean(member, members);
+                findLines(lines, new RegExp(`\\b${receiver}\\.${member}\\s*\\(`)).forEach((line) => issues.push({
+                    severity: "error",
+                    rule: "symbols/unknown-member",
+                    message: `\`${receivers[receiver]}.${member}()\` does not exist.${suggestion} The full member list is in \`llms.txt\`.`,
+                    line,
+                }));
+            }
+            return issues;
+        },
+    },
+    {
+        // `remember<SceneView-ish>` helper that isn't a real top-level function —
+        // e.g. an invented `rememberModelInstanceAsync`. Warning, not error: a
+        // snippet may legitimately mix non-SceneView Compose libraries whose
+        // helpers match the keyword net (e.g. Maps `rememberCameraPositionState`).
+        id: "symbols/unknown-remember-helper",
+        severity: "warning",
+        check(code, lines) {
+            const issues = [];
+            const sceneViewish = /^(Engine|Model|Material|Environment|Scene|Node|Collision|Render|Skybox|View|AR|Camera|Splat)/;
+            const callRe = /\bremember([A-Z]\w*)\s*\(/g;
+            const localNames = locallyDeclaredNames(code);
+            const seen = new Set();
+            for (const match of code.matchAll(callRe)) {
+                const fullName = `remember${match[1]}`;
+                if (seen.has(fullName))
+                    continue;
+                seen.add(fullName);
+                if (!sceneViewish.test(match[1]))
+                    continue;
+                if (localNames.has(fullName))
+                    continue;
+                if (isKnownTopLevelFunction(fullName))
+                    continue;
+                const suggestion = didYouMean(fullName, rememberHelperNames());
+                findLines(lines, new RegExp(`\\b${fullName}\\s*\\(`)).forEach((line) => issues.push({
+                    severity: "warning",
+                    rule: "symbols/unknown-remember-helper",
+                    message: `\`${fullName}\` is not a SceneView composable helper.${suggestion} If it comes from another library, add its import; otherwise check \`llms.txt\`.`,
+                    line,
+                }));
+            }
+            return issues;
+        },
+    },
 ];
 // ─── Swift Validation Rules ──────────────────────────────────────────────────
 const SWIFT_RULES = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sceneview-mcp",
-  "version": "4.0.14",
+  "version": "4.0.15",
   "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": [
@@ -59,12 +59,12 @@
     "node": ">=18"
   },
   "scripts": {
-    "prebuild": "node scripts/generate-llms-txt.js && node scripts/generate-version.js",
+    "prebuild": "node scripts/generate-llms-txt.js && node scripts/generate-version.js && node scripts/generate-symbols.js",
     "build": "tsc",
-    "prepare": "node scripts/generate-llms-txt.js && node scripts/generate-version.js && tsc",
+    "prepare": "node scripts/generate-llms-txt.js && node scripts/generate-version.js && node scripts/generate-symbols.js && tsc",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
-    "test": "node scripts/generate-llms-txt.js && node scripts/generate-version.js && vitest run",
+    "test": "node scripts/generate-llms-txt.js && node scripts/generate-version.js && node scripts/generate-symbols.js && vitest run",
     "biome": "cd .. && mcp/node_modules/.bin/biome check",
     "biome:fix": "cd .. && mcp/node_modules/.bin/biome check --write"
   },