Merge pull request #3 from Bigstonks1/dev-3

AGENTS.md

@@ -26,12 +26,13 @@ technical cutaway animation.
 - Fallback model path: `nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-NVFP4`
   through Transformers/custom code for the vision step if GGUF endpoint quality
   is not reliable enough for the demo.
-- Local code now serves a trusted `index.html` through `gradio.Server` and
-  exposes `/analyze_image` plus `/generate_scene`. The Space still needs a
-  GitHub-to-HF sync and private deployment verification for this pass.
-- Model-generated scene output is A-Frame declarative HTML
-  (`<a-scene>...</a-scene>`), with human-written deterministic Three.js as the
-  fallback in `index.html`.
+- Local code serves a trusted `index.html` through `gradio.Server` and exposes
+  `/analyze_image` plus compatibility `/generate_scene`. The latest deployed
+  private Space was verified before the June 14, 2026 review-security pass; any
+  new code changes still need the normal GitHub-to-HF sync and deployment
+  verification.
+- Scene rendering is deterministic browser-side Three.js from the validated
+  analysis JSON. Do not reintroduce model-authored HTML scene injection.
 - Endpoint naming is `generate_scene` everywhere in active code.
 - Bonus claims after Modal deployment: Llama Champion confirmed, NVIDIA
   Nemotron Quest confirmed, Off-Brand confirmed, Modal Award confirmed. Do not
@@ -53,8 +54,8 @@ technical cutaway animation.
 - `app.py` - Hugging Face Space entry point using `gradio.Server`; serves
   `index.html` at `/` and exposes `/analyze_image` plus `/generate_scene`.
 - `index.html` - self-contained HTML/CSS/JS shell loaded by `gradio.Server`;
-  includes A-Frame, Three.js, Gradio JS client, upload UI, pipeline
-  orchestration, and deterministic Three.js fallback.
+  includes Three.js, upload UI, source-photo preview, pipeline orchestration,
+  and deterministic Three.js rendering.
 - `modal_app.py` - Modal app scaffold with runtime asset caching, a
   llama.cpp GPU smoke-test function, a `runtime_probe` diagnostic endpoint, and
   placeholder plus experimental llama.cpp `analyze_image` / `generate_scene`
@@ -64,10 +65,7 @@ technical cutaway animation.
 - `snap2sim/__init__.py` - package marker.
 - `snap2sim/backend.py` - backend config, local placeholder inference, Modal
   HTTP client, and image base64 encoding.
-- `snap2sim/aframe_scene.py` - deterministic A-Frame scene generation for
-  local and placeholder Modal mode.
-- `snap2sim/prompts.py` - prompt templates for the vision analysis and A-Frame
-  scene-generation steps.
+- `snap2sim/prompts.py` - prompt template for the vision analysis step.
 - `snap2sim/schema.py` - structured JSON schema plus a sample mechanism payload.
 
 ## What Has Been Done
@@ -191,6 +189,16 @@ technical cutaway animation.
   on June 14, 2026: `/analyze_image` returned a validated mechanism payload
   through the secured Modal bearer-token flow, and `/generate_scene` returned
   an A-Frame `<a-scene>` block.
+- Implemented the `REVIEW.md` security pass on June 14, 2026:
+  Space-layer rate limiting for `/analyze_image` and `/generate_scene`,
+  upload-size caps, PIL decompression-bomb handling, clean image decode errors,
+  unique Modal temp image files with cleanup, and no model-authored scene HTML.
+- Consolidated rendering on deterministic browser-side Three.js from validated
+  analysis JSON. Removed the A-Frame runtime import, unused Gradio client
+  import, A-Frame scene builder, A-Frame scene prompt, and raw scene parser.
+- Updated the UI with source-photo preview, screen-reader live status, lighter
+  muted text, client-side image validation, keyboard-accessible drop zone, a
+  retry affordance, and a disabled initial Play state.
 
 ## Next Work
 

README.md

@@ -17,10 +17,10 @@ tinkerers and makers. It takes a hardware component photo, produces a
 structured mechanism analysis, and renders an animated technical cutaway
 visualization.
 
-The local app now serves a trusted `index.html` shell through `gradio.Server`
-and exposes `/analyze_image` plus `/generate_scene` routes. It still defaults
-to the placeholder backend locally, while the Modal llama.cpp path has been
-smoke-tested with the selected Nemotron GGUF and projector.
+The local app serves a trusted `index.html` shell through `gradio.Server` and
+exposes `/analyze_image` plus a compatibility `/generate_scene` route. It still
+defaults to the placeholder backend locally, while the Modal llama.cpp analysis
+path has been smoke-tested with the selected Nemotron GGUF and projector.
 
 ## Run Locally
 
@@ -100,34 +100,36 @@ generation, for about 26B total parameters.
 - `app.py` - Hugging Face Space entry point using `gradio.Server`; serves
   `index.html` at `/` and exposes `/analyze_image` plus `/generate_scene`.
 - `index.html` - plain HTML/CSS/JS shell with upload orchestration,
-  A-Frame injection, and deterministic browser-side Three.js fallback.
+  source-photo preview, and deterministic browser-side Three.js rendering.
 - `modal_app.py` - Modal web endpoint scaffold.
 - `scripts/verify_runtime_assets.py` - GGUF/mmproj metadata preflight.
 - `snap2sim/backend.py` - backend selection and HTTP client.
-- `snap2sim/aframe_scene.py` - deterministic A-Frame scene generation for
-  local and placeholder Modal mode.
-- `snap2sim/prompts.py` - prompt templates for vision and A-Frame generation.
+- `snap2sim/prompts.py` - prompt template for vision analysis.
 - `snap2sim/schema.py` - JSON schema and sample analysis payload.
 
 ## Current Rendering Architecture
 
 The app uses `gradio.Server` to serve `index.html` directly. This avoids
-Gradio component script stripping and lets the page load A-Frame and Three.js
-normally.
+Gradio component script stripping and lets the page load the trusted Three.js
+renderer normally.
 
 Runtime flow:
 
 1. Browser encodes the uploaded photo and posts it to `/analyze_image`.
 2. Backend returns the validated mechanism JSON.
-3. Browser posts the JSON to `/generate_scene`.
-4. The scene endpoint returns only an `<a-scene>...</a-scene>` block.
-5. Browser injects the A-Frame scene. If it is malformed or does not create a
-   canvas within 3 seconds, `buildDeterministicScene(json)` renders a
-   human-written Three.js fallback in the same viewport.
+3. Browser renders the cutaway directly from that JSON with deterministic
+   Three.js primitives.
+4. `/generate_scene` remains as a compatibility endpoint, but it returns a
+   validated `{ "renderer": "three", "analysis": ... }` scene descriptor
+   instead of model-authored HTML.
 
 The shell uses Chakra Petch and Fira Code from Bunny Fonts, an asymmetric
 63/37 viewport/readout split, a blueprint grid, amber/cyan instrument-panel
-colors, explicit Modal cold-start messaging, and a play/pause control.
+colors, explicit Modal cold-start messaging, source-photo preview, and a
+play/pause control.
+
+The browser no longer injects model-authored HTML into the DOM. The model's
+job is limited to the structured analysis JSON contract in `snap2sim/schema.py`.
 
 ## Modal Deployment Path
 
@@ -159,10 +161,11 @@ Useful deployment functions/endpoints:
   synthetic image and confirms it returns a validated mechanism payload.
 - `runtime_probe` reports the configured model repo, quant, projector file, and
   whether placeholder inference is still active.
-- `analyze_image` and `generate_scene` preserve the current HTTP contract for
-  the Gradio app.
-- `analyze_image_llamacpp` and `generate_scene_llamacpp` are experimental GPU
-  endpoints for the llama.cpp runtime path after the smoke test passes.
+- `analyze_image` preserves the HTTP contract for the Gradio app.
+- `generate_scene` and `generate_scene_llamacpp` are compatibility endpoints
+  that return the deterministic Three.js scene descriptor.
+- `analyze_image_llamacpp` is the experimental GPU endpoint for the llama.cpp
+  runtime path after the smoke test passes.
 
 Runtime environment knobs:
 
@@ -175,8 +178,8 @@ Runtime environment knobs:
 - `SNAP2SIM_RUNTIME_GPU`, default `L40S`
 
 Keep `SNAP2SIM_RUNTIME_MODE=placeholder` for the public demo unless you point
-`MODAL_ANALYZE_URL` at the validated `analyze_image_llamacpp` endpoint and keep
-`MODAL_GENERATE_URL` on deterministic `generate_scene`.
+`MODAL_ANALYZE_URL` at the validated `analyze_image_llamacpp` endpoint. The
+browser renders scenes deterministically from the validated analysis JSON.
 
 Run the deployment preflight in this order:
 
@@ -220,6 +223,10 @@ The Space also needs `SNAP2SIM_API_TOKEN` as a Hugging Face Space secret. The
 same value must be present in the Modal `snap2sim-api-auth` secret. Do not put
 that token in `.env.example`, README, logs, or prompts.
 
+Before making the Space public, keep the Space-layer protections active:
+`app.py` rate-limits `/analyze_image` and `/generate_scene`, rejects oversized
+base64/image payloads, and treats decompression-bomb images as request errors.
+
 From this repo, deploy after authenticating with Hugging Face:
 
 ```powershell

SECURITY.md

@@ -44,6 +44,11 @@ The Hugging Face Space at `jasondo111/Snap2Sim` is private as of the latest
 deployment. Future agents must not change the Space visibility to public unless
 the user explicitly asks for that action.
 
+The Space endpoints are same-origin browser APIs, not public credentials. Keep
+the server-side rate limits, upload-size caps, and image decompression-bomb
+guards in `app.py` active before any public launch. These controls reduce abuse
+of the Space as a trusted Modal proxy but do not replace the Modal bearer token.
+
 ## Environment Variables
 
 Safe to expose in public docs or `.env.example`:
@@ -82,12 +87,14 @@ Do not configure jobs that pull changes back from Hugging Face into GitHub.
 
 - Prefer Hugging Face Space variables for public configuration and Space secrets
   for credentials.
-- The planned `index.html` / `gradio.Server` frontend is public client-side
+- The `index.html` / `gradio.Server` frontend is public client-side
   code. Never embed `SNAP2SIM_API_TOKEN`, Modal endpoint URLs, Hugging Face
   tokens, or any credential-bearing values in HTML, JavaScript, CSS, bundled
   static assets, browser local storage, or query strings. Browser JS should call
   same-origin `@app.api()` endpoints; server-side Python should attach secrets
   when calling Modal.
+- Do not inject model-authored HTML, JavaScript, or A-Frame markup into the DOM.
+  Scene rendering should stay deterministic Three.js built from validated JSON.
 - Do not print secret-bearing environment variables in logs.
 - Do not paste full Modal or Hugging Face auth files into issues, docs, prompts,
   or Codex summaries.

app.py

@@ -3,12 +3,18 @@
 from __future__ import annotations
 
 import base64
+import binascii
+import threading
+import time
+import warnings
 from io import BytesIO
 from pathlib import Path
 from typing import Any, Callable
 
+from fastapi import HTTPException, Request
 from fastapi.responses import HTMLResponse
-from PIL import Image
+from fastapi.responses import JSONResponse
+from PIL import Image, UnidentifiedImageError
 
 from snap2sim.backend import InferenceClient, Settings
 
@@ -37,6 +43,32 @@ except ImportError:
 
 app = Server()
 INDEX_PATH = Path(__file__).with_name("index.html")
+MAX_IMAGE_BASE64_CHARS = 12 * 1024 * 1024
+MAX_IMAGE_BYTES = 9 * 1024 * 1024
+MAX_IMAGE_PIXELS = 12_000_000
+RATE_LIMIT_WINDOW_SECONDS = 60
+RATE_LIMIT_PER_CLIENT = 12
+RATE_LIMIT_GLOBAL = 72
+RATE_LIMIT_PATHS = {"/analyze_image", "/generate_scene"}
+
+Image.MAX_IMAGE_PIXELS = MAX_IMAGE_PIXELS
+
+_rate_lock = threading.Lock()
+_client_hits: dict[str, list[float]] = {}
+_global_hits: list[float] = []
+
+
+@app.middleware("http")
+async def rate_limit_api(request: Request, call_next: Callable[..., Any]) -> Any:
+    if request.method == "POST" and request.url.path in RATE_LIMIT_PATHS:
+        allowed, retry_after = _record_request(_client_id(request))
+        if not allowed:
+            return JSONResponse(
+                {"detail": f"Rate limit exceeded. Retry after {retry_after} seconds."},
+                status_code=429,
+                headers={"Retry-After": str(retry_after)},
+            )
+    return await call_next(request)
 
 
 @app.get("/", response_class=HTMLResponse)
@@ -67,13 +99,13 @@ def analyze_image_http(payload: dict[str, Any]) -> dict[str, Any]:
 
 
 @app.api(name="generate_scene")
-def generate_scene_api(analysis: dict[str, Any]) -> str:
+def generate_scene_api(analysis: dict[str, Any]) -> dict[str, Any]:
     return _generate_scene(analysis)
 
 
 @app.post("/generate_scene")
-def generate_scene_http(payload: dict[str, Any]) -> dict[str, str]:
-    return {"html": _generate_scene(payload.get("analysis") or {})}
+def generate_scene_http(payload: dict[str, Any]) -> dict[str, Any]:
+    return _generate_scene(payload.get("analysis") or {})
 
 
 def _analyze_image(image_base64: str) -> dict[str, Any]:
@@ -81,15 +113,61 @@ def _analyze_image(image_base64: str) -> dict[str, Any]:
     return InferenceClient(Settings()).analyze_image(image)
 
 
-def _generate_scene(analysis: dict[str, Any]) -> str:
+def _generate_scene(analysis: dict[str, Any]) -> dict[str, Any]:
     return InferenceClient(Settings()).generate_scene(analysis)
 
 
 def _decode_image(image_base64: str) -> Image.Image:
     if "," in image_base64 and image_base64.lstrip().startswith("data:"):
         image_base64 = image_base64.split(",", 1)[1]
-    raw = base64.b64decode(image_base64)
-    return Image.open(BytesIO(raw)).convert("RGB")
+    if len(image_base64) > MAX_IMAGE_BASE64_CHARS:
+        raise HTTPException(status_code=413, detail="Image upload is too large.")
+    try:
+        raw = base64.b64decode(image_base64, validate=True)
+    except (binascii.Error, ValueError) as exc:
+        raise HTTPException(status_code=400, detail="Image payload is not valid base64.") from exc
+    if len(raw) > MAX_IMAGE_BYTES:
+        raise HTTPException(status_code=413, detail="Image upload is too large.")
+
+    try:
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", Image.DecompressionBombWarning)
+            image = Image.open(BytesIO(raw))
+            image.load()
+    except Image.DecompressionBombWarning as exc:
+        raise HTTPException(status_code=413, detail="Image dimensions are too large.") from exc
+    except Image.DecompressionBombError as exc:
+        raise HTTPException(status_code=413, detail="Image dimensions are too large.") from exc
+    except (UnidentifiedImageError, OSError, ValueError) as exc:
+        raise HTTPException(status_code=400, detail="Upload a valid image file.") from exc
+
+    if image.width * image.height > MAX_IMAGE_PIXELS:
+        raise HTTPException(status_code=413, detail="Image dimensions are too large.")
+    return image.convert("RGB")
+
+
+def _client_id(request: Request) -> str:
+    forwarded_for = request.headers.get("x-forwarded-for", "")
+    if forwarded_for:
+        return forwarded_for.split(",", 1)[0].strip()
+    return request.client.host if request.client else "unknown"
+
+
+def _record_request(client_id: str) -> tuple[bool, int]:
+    now = time.monotonic()
+    cutoff = now - RATE_LIMIT_WINDOW_SECONDS
+    with _rate_lock:
+        _global_hits[:] = [hit for hit in _global_hits if hit >= cutoff]
+        hits = [hit for hit in _client_hits.get(client_id, []) if hit >= cutoff]
+        if len(hits) >= RATE_LIMIT_PER_CLIENT or len(_global_hits) >= RATE_LIMIT_GLOBAL:
+            oldest = min(hits[0] if hits else now, _global_hits[0] if _global_hits else now)
+            retry_after = max(1, int(RATE_LIMIT_WINDOW_SECONDS - (now - oldest)))
+            _client_hits[client_id] = hits
+            return False, retry_after
+        hits.append(now)
+        _global_hits.append(now)
+        _client_hits[client_id] = hits
+    return True, 0
 
 
 if __name__ == "__main__":

index.html

@@ -6,10 +6,19 @@
   <title>Inside the Machine</title>
   <link rel="preconnect" href="https://fonts.bunny.net">
   <link href="https://fonts.bunny.net/css?family=chakra-petch:400,500,600,700|fira-code:400,500,600" rel="stylesheet">
-  <script src="https://aframe.io/releases/1.6.0/aframe.min.js"></script>
+  <script type="importmap">
+    {
+      "imports": {
+        "three": "https://cdn.jsdelivr.net/npm/three@0.160.1/build/three.module.js",
+        "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.160.1/examples/jsm/"
+      }
+    }
+  </script>
   <script type="module">
-    import { Client } from "https://cdn.jsdelivr.net/npm/@gradio/client/dist/index.min.js";
-    window.snap2simGradioClient = Client;
+    import * as THREE from "three";
+    import { OrbitControls } from "three/addons/controls/OrbitControls.js";
+
+    window.THREE = { ...THREE, OrbitControls };
   </script>
   <style>
     :root {
@@ -21,7 +30,7 @@
       --cyan: #5FD4D0;
       --cyan-dim: #2A5E5C;
       --text: #C8C0AC;
-      --text-muted: #6B7280;
+      --text-muted: #9CA3AF;
       --grid: rgba(255,255,255,0.04);
       --danger: #F07F5A;
     }
@@ -81,16 +90,6 @@
       z-index: 1;
     }
 
-    #viewport a-scene {
-      width: 100%;
-      height: 100%;
-    }
-
-    #viewport .a-enter-vr,
-    #viewport .a-orientation-modal {
-      display: none !important;
-    }
-
     .drop-zone {
       position: absolute;
       inset: 18px;
@@ -246,6 +245,41 @@
       color: var(--danger);
     }
 
+    .retry-button {
+      justify-self: start;
+      min-height: 32px;
+      border: 1px solid var(--danger);
+      border-radius: 0;
+      color: var(--danger);
+      background: transparent;
+      text-transform: uppercase;
+      letter-spacing: 0;
+      cursor: pointer;
+    }
+
+    .retry-button[hidden] {
+      display: none;
+    }
+
+    .source-card {
+      display: grid;
+      gap: 8px;
+      border-bottom: 1px solid rgba(95, 212, 208, 0.16);
+      padding-bottom: 14px;
+    }
+
+    .source-card[hidden] {
+      display: none;
+    }
+
+    .source-image {
+      width: 100%;
+      max-height: 150px;
+      object-fit: cover;
+      border: 1px solid rgba(122, 84, 32, 0.72);
+      background: var(--bg);
+    }
+
     .readout {
       display: grid;
       gap: 18px;
@@ -376,12 +410,12 @@
       <div id="progress" class="progress"></div>
       <div class="toolbar">
         <button id="uploadButton" class="tool-button" type="button">Load</button>
-        <button id="playButton" class="tool-button" type="button" disabled>Pause</button>
+        <button id="playButton" class="tool-button" type="button" disabled>Play</button>
       </div>
-      <div id="viewport"></div>
-      <label id="dropZone" class="drop-zone" for="fileInput">Drop component photo</label>
+      <div id="viewport" aria-hidden="true"></div>
+      <label id="dropZone" class="drop-zone" for="fileInput" tabindex="0">Drop component photo</label>
       <div id="scanLine" class="scan-line"></div>
-      <input id="fileInput" type="file" accept="image/*" hidden>
+      <input id="fileInput" type="file" accept="image/*" capture="environment" hidden>
     </section>
 
     <aside class="panel">
@@ -389,9 +423,15 @@
         <header class="brand">
           <div class="kicker">Snap2Sim</div>
           <h1>Inside the Machine</h1>
-          <div id="status" class="status">Standby</div>
+          <div id="status" class="status" role="status" aria-live="polite">Standby</div>
+          <button id="retryButton" class="retry-button" type="button" hidden>Try another photo</button>
         </header>
 
+        <section id="sourceCard" class="source-card" hidden>
+          <div class="label">Source Photo</div>
+          <img id="sourceImage" class="source-image" alt="Uploaded component photo preview">
+        </section>
+
         <section class="readout">
           <div class="metric-row">
             <div id="component" class="component">Awaiting Photo</div>
@@ -426,6 +466,9 @@
     const progress = document.getElementById("progress");
     const scanLine = document.getElementById("scanLine");
     const statusEl = document.getElementById("status");
+    const retryButton = document.getElementById("retryButton");
+    const sourceCard = document.getElementById("sourceCard");
+    const sourceImage = document.getElementById("sourceImage");
     const componentEl = document.getElementById("component");
     const confidenceEl = document.getElementById("confidence");
     const summaryEl = document.getElementById("summary");
@@ -438,8 +481,11 @@
     let paused = false;
     let coldStartTimer = 0;
     let fallbackRuntime = null;
+    let currentPreviewUrl = "";
+    const MAX_CLIENT_IMAGE_BYTES = 8 * 1024 * 1024;
 
     uploadButton.addEventListener("click", () => fileInput.click());
+    retryButton.addEventListener("click", () => fileInput.click());
     fileInput.addEventListener("change", () => {
       const file = fileInput.files && fileInput.files[0];
       if (file) runPipeline(file);
@@ -459,6 +505,13 @@
       });
     }
 
+    dropZone.addEventListener("keydown", (event) => {
+      if (event.key === "Enter" || event.key === " ") {
+        event.preventDefault();
+        fileInput.click();
+      }
+    });
+
     dropZone.addEventListener("drop", (event) => {
       const file = event.dataTransfer.files && event.dataTransfer.files[0];
       if (file) runPipeline(file);
@@ -467,15 +520,20 @@
     playButton.addEventListener("click", () => {
       paused = !paused;
       playButton.textContent = paused ? "Resume" : "Pause";
-      if (activeMode === "aframe") {
-        const scene = viewport.querySelector("a-scene");
-        if (scene) paused ? scene.pause() : scene.play();
-      }
       if (fallbackRuntime) fallbackRuntime.playing = !paused;
     });
 
     async function runPipeline(file) {
+      const validationError = validateFile(file);
+      if (validationError) {
+        setStatus(validationError, true);
+        retryButton.hidden = false;
+        dropZone.classList.remove("hidden");
+        return;
+      }
+
       resetScene();
+      showSourcePreview(file);
       setBusy(true);
       setStatus("ANALYZING ASSEMBLY...");
       coldStartTimer = window.setTimeout(() => setStatus("WAKING THE WORKSHOP..."), 6500);
@@ -487,12 +545,12 @@
         populateAnalysis(analysis);
 
         setStatus("RENDERING CUTAWAY...");
-        const sceneResponse = await postJson("/generate_scene", { analysis });
-        const sceneHtml = typeof sceneResponse === "string" ? sceneResponse : sceneResponse.html;
-        renderAframe(sceneHtml, analysis);
+        buildDeterministicScene(analysis);
       } catch (error) {
         window.clearTimeout(coldStartTimer);
         setStatus(error.message || String(error), true);
+        retryButton.hidden = false;
+        dropZone.classList.remove("hidden");
         if (window.lastAnalysis) buildDeterministicScene(window.lastAnalysis);
       } finally {
         setBusy(false);
@@ -504,8 +562,9 @@
       fallbackRuntime = null;
       activeMode = "idle";
       paused = false;
-      playButton.textContent = "Pause";
+      playButton.textContent = "Play";
       playButton.disabled = true;
+      retryButton.hidden = true;
       viewport.replaceChildren();
       dropZone.classList.add("hidden");
     }
@@ -535,35 +594,8 @@
       }));
     }
 
-    function renderAframe(sceneHtml, analysis) {
-      if (!sceneHtml || !/<a-scene[\s>]/i.test(sceneHtml) || !/<\/a-scene>/i.test(sceneHtml)) {
-        buildDeterministicScene(analysis);
-        return;
-      }
-
-      activeMode = "aframe";
-      viewport.innerHTML = sceneHtml;
-      const scene = viewport.querySelector("a-scene");
-      if (scene) {
-        scene.setAttribute("embedded", "");
-        scene.setAttribute("vr-mode-ui", "enabled: false");
-        scene.setAttribute("device-orientation-permission-ui", "enabled: false");
-        scene.setAttribute("background", "color: #0F1318");
-      }
-      playButton.disabled = false;
-      revealScan();
-
-      window.setTimeout(() => {
-        const liveScene = viewport.querySelector("a-scene");
-        const hasCanvas = Boolean(liveScene && liveScene.canvas);
-        if (!hasCanvas) buildDeterministicScene(analysis);
-      }, 3000);
-
-      setStatus("CUTAWAY READY");
-    }
-
     function buildDeterministicScene(analysis) {
-      const threeRuntime = window.THREE || (window.AFRAME && window.AFRAME.THREE);
+      const threeRuntime = window.THREE;
       if (!threeRuntime) {
         setStatus("3D RUNTIME UNAVAILABLE", true);
         return;
@@ -575,10 +607,16 @@
       paused = false;
       playButton.textContent = "Pause";
       playButton.disabled = false;
-      viewport.innerHTML = '<div class="fallback-stage"><div class="scene-mount"></div><div class="label-layer"></div></div>';
+      viewport.replaceChildren();
+      const stage = document.createElement("div");
+      stage.className = "fallback-stage";
+      const mount = document.createElement("div");
+      mount.className = "scene-mount";
+      const labelLayer = document.createElement("div");
+      labelLayer.className = "label-layer";
+      stage.append(mount, labelLayer);
+      viewport.append(stage);
 
-      const mount = viewport.querySelector(".scene-mount");
-      const labelLayer = viewport.querySelector(".label-layer");
       const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
       renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
       mount.appendChild(renderer.domElement);
@@ -667,6 +705,23 @@
       setStatus("CUTAWAY READY");
     }
 
+    function validateFile(file) {
+      if (!file.type || !file.type.startsWith("image/")) {
+        return "Upload an image file.";
+      }
+      if (file.size > MAX_CLIENT_IMAGE_BYTES) {
+        return "Image must be 8 MB or smaller.";
+      }
+      return "";
+    }
+
+    function showSourcePreview(file) {
+      if (currentPreviewUrl) URL.revokeObjectURL(currentPreviewUrl);
+      currentPreviewUrl = URL.createObjectURL(file);
+      sourceImage.src = currentPreviewUrl;
+      sourceCard.hidden = false;
+    }
+
     function buildPartMesh(part, index) {
       const geometryData = part.geometry || {};
       const size = Array.isArray(geometryData.size) ? geometryData.size : [1, 1, 1];

modal_app.py

@@ -16,9 +16,8 @@ import secrets as token_secrets
 import modal
 from fastapi import Header, HTTPException
 
-from snap2sim.aframe_scene import build_aframe_scene
-from snap2sim.model_io import coerce_analysis_response, parse_analysis_response, parse_scene_response
-from snap2sim.prompts import build_scene_prompt, build_vision_prompt
+from snap2sim.model_io import coerce_analysis_response, parse_analysis_response
+from snap2sim.prompts import build_vision_prompt
 from snap2sim.schema import EXAMPLE_ANALYSIS, validate_analysis
 
 
@@ -29,6 +28,9 @@ DEFAULT_RUNTIME_MODE = "placeholder"
 CACHE_DIR = "/cache"
 HF_CACHE_DIR = f"{CACHE_DIR}/huggingface"
 MODEL_ASSET_DIR = f"{CACHE_DIR}/models"
+MAX_IMAGE_BASE64_CHARS = 12 * 1024 * 1024
+MAX_IMAGE_BYTES = 9 * 1024 * 1024
+MAX_IMAGE_PIXELS = 12_000_000
 
 
 model_cache = modal.Volume.from_name("snap2sim-hf-cache", create_if_missing=True)
@@ -81,14 +83,12 @@ def check_remote_imports() -> dict[str, Any]:
     """Lightweight Modal check that local project modules are packaged."""
     import snap2sim.model_io
     import snap2sim.schema
-    import snap2sim.aframe_scene
 
     return {
         "ok": True,
         "modules": [
             snap2sim.model_io.__name__,
             snap2sim.schema.__name__,
-            snap2sim.aframe_scene.__name__,
         ],
     }
 
@@ -191,12 +191,15 @@ def smoke_test_llamacpp_image() -> dict[str, Any]:
     """Run one image prompt through llama.cpp's multimodal CLI on a GPU."""
     import base64
     import subprocess
+    import tempfile
     import time
 
     from PIL import Image, ImageDraw
 
     model_path, mmproj_path = ensure_runtime_assets()
-    test_image = Path("/tmp/snap2sim-smoke-input.jpg")
+    temp_file = tempfile.NamedTemporaryFile(prefix="snap2sim-smoke-", suffix=".jpg", delete=False)
+    temp_file.close()
+    test_image = Path(temp_file.name)
     img = Image.new("RGB", (512, 384), "#d8d0bd")
     draw = ImageDraw.Draw(img)
     draw.rectangle((82, 96, 430, 288), outline="#2c3138", width=8)
@@ -265,6 +268,8 @@ def smoke_test_llamacpp_image() -> dict[str, Any]:
         and "image input is not supported" not in combined_output.lower()
         and "failed to load projector" not in combined_output.lower()
     )
+    image_base64_prefix = base64.b64encode(test_image.read_bytes()).decode("ascii")[:80]
+    test_image.unlink(missing_ok=True)
     return {
         "ok": image_supported and valid_json,
         "image_supported": image_supported,
@@ -275,7 +280,7 @@ def smoke_test_llamacpp_image() -> dict[str, Any]:
         "elapsed_seconds": elapsed_seconds,
         "model_path": str(model_path),
         "mmproj_path": str(mmproj_path),
-        "image_base64_prefix": base64.b64encode(test_image.read_bytes()).decode("ascii")[:80],
+        "image_base64_prefix": image_base64_prefix,
         "stdout_tail": stdout[-4000:],
         "stderr_tail": stderr[-4000:],
     }
@@ -327,35 +332,66 @@ def run_llamacpp_prompt(
 def write_payload_image(payload: dict[str, Any]) -> Path:
     """Decode an image_base64 payload into a temporary RGB JPEG."""
     import base64
+    import binascii
+    import tempfile
+    import warnings
     from io import BytesIO
 
-    from PIL import Image
+    from PIL import Image, UnidentifiedImageError
 
+    Image.MAX_IMAGE_PIXELS = MAX_IMAGE_PIXELS
     image_base64 = payload.get("image_base64")
     if not isinstance(image_base64, str) or not image_base64:
         raise ValueError("Request payload must include image_base64.")
     if "," in image_base64 and image_base64.lstrip().startswith("data:"):
         image_base64 = image_base64.split(",", 1)[1]
+    if len(image_base64) > MAX_IMAGE_BASE64_CHARS:
+        raise ValueError("Image upload is too large.")
 
-    raw = base64.b64decode(image_base64)
-    image = Image.open(BytesIO(raw)).convert("RGB")
-    path = Path("/tmp/snap2sim-request-image.jpg")
+    try:
+        raw = base64.b64decode(image_base64, validate=True)
+    except (binascii.Error, ValueError) as exc:
+        raise ValueError("Image payload is not valid base64.") from exc
+    if len(raw) > MAX_IMAGE_BYTES:
+        raise ValueError("Image upload is too large.")
+
+    try:
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", Image.DecompressionBombWarning)
+            image = Image.open(BytesIO(raw))
+            image.load()
+    except Image.DecompressionBombWarning as exc:
+        raise ValueError("Image dimensions are too large.") from exc
+    except Image.DecompressionBombError as exc:
+        raise ValueError("Image dimensions are too large.") from exc
+    except (UnidentifiedImageError, OSError, ValueError) as exc:
+        raise ValueError("Upload a valid image file.") from exc
+    if image.width * image.height > MAX_IMAGE_PIXELS:
+        raise ValueError("Image dimensions are too large.")
+
+    temp_file = tempfile.NamedTemporaryFile(prefix="snap2sim-request-", suffix=".jpg", delete=False)
+    temp_file.close()
+    path = Path(temp_file.name)
+    image = image.convert("RGB")
     image.save(path, format="JPEG", quality=92)
     return path
 
 
 def analyze_image_llamacpp_payload(payload: dict[str, Any]) -> dict[str, Any]:
     image_path = write_payload_image(payload)
-    response = run_llamacpp_prompt(
-        build_vision_prompt(),
-        image_path=image_path,
-        max_tokens=1536,
-        timeout_seconds=180,
-    )
     try:
-        return parse_analysis_response(response)
-    except Exception:
-        return coerce_analysis_response(response)
+        response = run_llamacpp_prompt(
+            build_vision_prompt(),
+            image_path=image_path,
+            max_tokens=1536,
+            timeout_seconds=180,
+        )
+        try:
+            return parse_analysis_response(response)
+        except Exception:
+            return coerce_analysis_response(response)
+    finally:
+        image_path.unlink(missing_ok=True)
 
 
 @app.local_entrypoint()
@@ -447,23 +483,20 @@ def analyze_image_llamacpp(payload: dict[str, Any], authorization: str = Header(
 
 @app.function(image=image, volumes={CACHE_DIR: model_cache}, timeout=600, secrets=[api_auth_secret])
 @modal.fastapi_endpoint(method="POST")
-def generate_scene(payload: dict[str, Any], authorization: str = Header(default="")) -> dict[str, str]:
+def generate_scene(payload: dict[str, Any], authorization: str = Header(default="")) -> dict[str, Any]:
     require_authorization(authorization)
     analysis = validate_analysis(payload.get("analysis") or EXAMPLE_ANALYSIS)
-    _prompt = build_scene_prompt(analysis)
     if runtime_config()["runtime_mode"] != "placeholder":
         raise NotImplementedError(
-            "Nemotron runtime is selected but not wired yet. Keep placeholder "
-            "mode active until the llama.cpp/vLLM adapter is implemented."
+            "Scene generation is deterministic in the browser from validated JSON."
         )
-    return {"html": build_aframe_scene(analysis)}
+    return {"renderer": "three", "analysis": analysis}
 
 
 @app.function(image=llamacpp_image, gpu=os.getenv("SNAP2SIM_RUNTIME_GPU", "L40S"), volumes={CACHE_DIR: model_cache}, timeout=60 * 60, secrets=[api_auth_secret])
 @modal.fastapi_endpoint(method="POST")
-def generate_scene_llamacpp(payload: dict[str, Any], authorization: str = Header(default="")) -> dict[str, str]:
-    """Experimental GPU endpoint for llama.cpp A-Frame scene generation."""
+def generate_scene_llamacpp(payload: dict[str, Any], authorization: str = Header(default="")) -> dict[str, Any]:
+    """Compatibility endpoint; scene rendering is deterministic browser-side."""
     require_authorization(authorization)
     analysis = validate_analysis(payload.get("analysis") or EXAMPLE_ANALYSIS)
-    response = run_llamacpp_prompt(build_scene_prompt(analysis), max_tokens=4096)
-    return {"html": parse_scene_response(response)}
+    return {"renderer": "three", "analysis": analysis}

snap2sim/aframe_scene.py

@@ -1,120 +0,0 @@
-"""Deterministic A-Frame scene generation from a validated mechanism payload."""
-
-from __future__ import annotations
-
-import html
-from typing import Any
-
-from snap2sim.schema import validate_analysis
-
-
-def build_aframe_scene(analysis: dict[str, Any]) -> str:
-    """Return a declarative A-Frame scene for the browser to inject."""
-    valid_analysis = validate_analysis(analysis)
-    title = html.escape(str(valid_analysis.get("component", "mechanism")).upper(), quote=True)
-    summary = html.escape(str(valid_analysis.get("summary", "")), quote=True)
-    entities = "\n".join(_part_entity(part, index) for index, part in enumerate(valid_analysis["parts"][:6]))
-    return f"""<a-scene embedded vr-mode-ui="enabled: false" device-orientation-permission-ui="enabled: false" background="color: #0F1318" renderer="colorManagement: true">
-  <a-sky color="#0F1318"></a-sky>
-  <a-entity light="type: ambient; intensity: 0.55; color: #5FD4D0"></a-entity>
-  <a-entity light="type: directional; intensity: 1.35; color: #E8A33D" position="3 5 4"></a-entity>
-  <a-entity position="0 1.1 5.6">
-    <a-camera look-controls wasd-controls="enabled: false"></a-camera>
-  </a-entity>
-  <a-plane color="#111820" opacity="0.72" rotation="-90 0 0" position="0 -1.05 -0.2" width="8" height="8"></a-plane>
-  <a-text value="{title}" position="-2.8 2.35 -2.6" color="#C8C0AC" width="4.8" align="left"></a-text>
-  <a-text value="{summary}" position="-2.8 2.05 -2.6" color="#6B7280" width="5.2" align="left"></a-text>
-{entities}
-</a-scene>"""
-
-
-def _part_entity(part: dict[str, Any], index: int) -> str:
-    geometry = part["geometry"]
-    shape = geometry["shape"]
-    size = geometry["size"]
-    position = _vec(geometry["position"])
-    rotation = _rotation(geometry.get("rotation", [0, 0, 0]))
-    color = _color(geometry.get("color"), index)
-    label = html.escape(str(part.get("name", part.get("id", "part"))), quote=True)
-    animation = _animation(part)
-
-    if shape in {"cylinder", "gear"}:
-        radius = max(float(size[0]), float(size[2])) / 2
-        primitive = (
-            f'<a-cylinder radius="{radius:.3f}" height="{float(size[1]):.3f}" '
-            f'segments-radial="{int(geometry.get("teeth", 32)) if shape == "gear" else 48}"'
-        )
-    elif shape == "sphere":
-        primitive = f'<a-sphere radius="{max(float(item) for item in size) / 2:.3f}"'
-    elif shape == "rod":
-        primitive = f'<a-cylinder radius="{max(float(size[0]), float(size[1])) / 2:.3f}" height="{float(size[2]):.3f}"'
-        rotation = _rotation([1.5708, 0, 0])
-    else:
-        primitive = f'<a-box width="{float(size[0]):.3f}" height="{float(size[1]):.3f}" depth="{float(size[2]):.3f}"'
-
-    return f"""  <a-entity position="{position}">
-    {primitive} material="color: {color}; metalness: 0.45; roughness: 0.38" rotation="{rotation}" {animation}></a-cylinder>
-    <a-text value="{label}" position="0 {float(size[1]) + 0.28:.3f} 0" color="#5FD4D0" width="2.4" align="center"></a-text>
-  </a-entity>""".replace("</a-cylinder>", _closing_tag(shape))
-
-
-def _closing_tag(shape: str) -> str:
-    if shape == "sphere":
-        return "</a-sphere>"
-    if shape == "box":
-        return "</a-box>"
-    return "</a-cylinder>"
-
-
-def _animation(part: dict[str, Any]) -> str:
-    motion = part.get("motion") or {"type": "static"}
-    motion_type = motion.get("type")
-    if motion_type == "static":
-        return ""
-
-    speed = max(0.1, abs(float(motion.get("speed", 1))))
-    duration = int(max(700, min(9000, 3600 / speed)))
-    axis = motion.get("axis") if isinstance(motion.get("axis"), list) else [0, 1, 0]
-
-    if motion_type == "translate":
-        move_range = motion.get("range") if isinstance(motion.get("range"), list) else [-0.25, 0.25]
-        target = [float(axis[i]) * float(move_range[-1]) for i in range(3)]
-        return (
-            f'animation="property: position; to: {_vec(target)}; dir: alternate; '
-            f'loop: true; dur: {duration}; easing: easeInOutSine"'
-        )
-
-    rotation = [0, 0, 0]
-    if abs(float(axis[0])) >= max(abs(float(axis[1])), abs(float(axis[2]))):
-        rotation[0] = 360
-    elif abs(float(axis[2])) >= abs(float(axis[1])):
-        rotation[2] = 360
-    else:
-        rotation[1] = 360
-    if motion_type == "oscillate":
-        amplitude = int(float(motion.get("amplitude", 0.25)) * 90)
-        rotation = [value and amplitude for value in rotation]
-        return (
-            f'animation="property: rotation; to: {_vec(rotation)}; dir: alternate; '
-            f'loop: true; dur: {duration}; easing: easeInOutSine"'
-        )
-    return f'animation="property: rotation; to: {_vec(rotation)}; loop: true; dur: {duration}; easing: linear"'
-
-
-def _vec(values: list[Any]) -> str:
-    return " ".join(f"{float(value):.3f}" for value in values)
-
-
-def _rotation(values: list[Any]) -> str:
-    return " ".join(f"{float(value) * 57.2958:.2f}" for value in values)
-
-
-def _color(value: Any, index: int) -> str:
-    key = str(value or "").lower()
-    if "amber" in key or "orange" in key:
-        return "#E8A33D"
-    if "cyan" in key:
-        return "#5FD4D0"
-    if "steel" in key:
-        return "#9AA4A6"
-    return ["#5FD4D0", "#E8A33D", "#C8C0AC", "#80B8FF", "#F07F5A", "#A7D676"][index % 6]

snap2sim/backend.py

@@ -11,7 +11,6 @@ from typing import Any
 import requests
 from PIL import Image
 
-from snap2sim.aframe_scene import build_aframe_scene
 from snap2sim.schema import EXAMPLE_ANALYSIS, validate_analysis
 
 
@@ -45,16 +44,9 @@ class InferenceClient:
 
         return validate_analysis(dict(EXAMPLE_ANALYSIS))
 
-    def generate_scene(self, analysis: dict[str, Any]) -> str:
+    def generate_scene(self, analysis: dict[str, Any]) -> dict[str, Any]:
         valid_analysis = validate_analysis(analysis)
-        if self.settings.backend == "modal":
-            response = self._post_json(self.settings.generate_url, {"analysis": valid_analysis})
-            html = response.get("html", "")
-            if not html:
-                raise RuntimeError("Modal response did not include generated HTML.")
-            return str(html)
-
-        return build_aframe_scene(valid_analysis)
+        return {"renderer": "three", "analysis": valid_analysis}
 
     def _post_json(self, url: str, payload: dict[str, Any]) -> dict[str, Any]:
         if not url:

snap2sim/model_io.py

@@ -46,17 +46,6 @@ def coerce_analysis_response(text: str) -> dict[str, Any]:
     return validate_analysis(_generic_analysis(fallback_component))
 
 
-def parse_scene_response(text: str) -> str:
-    """Extract a complete A-Frame scene block from a model response."""
-    raw = _strip_fences(text).strip()
-    lowered = raw.lower()
-    scene_start = lowered.find("<a-scene")
-    scene_end = lowered.rfind("</a-scene>")
-    if scene_start < 0 or scene_end < 0:
-        raise ValueError("Model response did not contain a complete <a-scene> block.")
-    return raw[scene_start : scene_end + len("</a-scene>")]
-
-
 def _strip_fences(text: str) -> str:
     return _FENCE_RE.sub("", text.strip()).strip()
 

snap2sim/prompts.py

@@ -1,11 +1,7 @@
-"""Prompt templates for the two model calls."""
+"""Prompt templates for model calls."""
 
 from __future__ import annotations
 
-import json
-from typing import Any
-
-
 VISION_SYSTEM_PROMPT = """You are a mechanical teardown analyst.
 Given an image of a hardware component, infer the most likely internal
 mechanism and return only JSON matching the provided schema. Prefer clear,
@@ -18,7 +14,7 @@ def build_vision_prompt() -> str:
         "Analyze the uploaded hardware component as a cutaway mechanism. "
         "Answer with only one JSON object. Do not include markdown. Do not "
         "include a reasoning trace or <think> tags. Keep the payload compact and physically "
-        "plausible for primitive A-Frame or Three.js rendering.\n\n"
+        "plausible for primitive Three.js rendering.\n\n"
         "Required top-level keys: component, confidence, summary, trigger, "
         "motion_sequence, parts.\n"
         "Each part requires: id, name, role, geometry, motion.\n"
@@ -46,25 +42,3 @@ def build_vision_prompt() -> str:
         "fields: axis, speed, amplitude, phase, range. Include optional fields "
         "only when useful."
     )
-
-
-AFRAME_SYSTEM_PROMPT = """You generate declarative A-Frame cutaway scenes.
-Return only one <a-scene>...</a-scene> block. Use primitive A-Frame entities,
-short labels, and animation attributes. Do not include scripts, markdown fences,
-explanations, or a complete HTML document."""
-
-
-def build_scene_prompt(analysis: dict[str, Any]) -> str:
-    return (
-        "Build a technical cutaway / field manual A-Frame animation for this "
-        "mechanism analysis. Return only the <a-scene>...</a-scene> block. "
-        "Use 3 to 6 visible primitive parts maximum, selected from <a-box>, "
-        "<a-cylinder>, <a-sphere>, <a-torus>, <a-cone>, and <a-entity>. "
-        "Include <a-sky color=\"#0F1318\">, a camera, lights, short <a-text> "
-        "labels, warm amber annotations, and cool cyan moving parts. Use "
-        "A-Frame animation attributes for motion, for example "
-        "animation=\"property: rotation; to: 0 360 0; loop: true; dur: 2000; "
-        "easing: linear\". Do not include scripts, markdown, explanations, "
-        "or a complete HTML document.\n\n"
-        f"Mechanism JSON:\n{json.dumps(analysis, indent=2)}"
-    )