Migrate Snap2Sim to trusted HTML scene shell

Co-authored-by: OpenAI Codex <codex@openai.com>

.github/workflows/sync_to_hf.yml

@@ -57,4 +57,14 @@ jobs:
         run: git lfs push huggingface --all
 
       - name: Force-sync main to Hugging Face
-        run: git push --force huggingface HEAD:main
+        run: |
+          for attempt in 1 2 3 4 5; do
+            if git push --force huggingface HEAD:main; then
+              exit 0
+            fi
+            delay=$((attempt * 20))
+            echo "Hugging Face push failed on attempt ${attempt}; retrying in ${delay}s..." >&2
+            sleep "$delay"
+          done
+          echo "Hugging Face push failed after 5 attempts." >&2
+          exit 1

AGENTS.md

@@ -2,10 +2,10 @@
 
 ## Project Overview
 
-Snap2Sim / Inside the Machine is a Gradio-based Hugging Face Space scaffold for
-the Build Small Hackathon Backyard AI track. The app is intended to accept a
-photo of a hardware component, infer its internal mechanism, and render an
-annotated technical cutaway animation.
+Snap2Sim / Inside the Machine is a Build Small Hackathon Backyard AI project
+for curious tinkerers and makers. The app is intended to accept a photo of a
+hardware component, infer its internal mechanism, and render an annotated
+technical cutaway animation.
 
 ## Runtime Notes
 
@@ -18,8 +18,17 @@ annotated 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.
-- Current code uses placeholder inference so the UI, schema, and endpoint
-  contract can run without downloading large model weights.
+- 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`.
+- 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
+  claim Off the Grid unless the final deployment moves inference to ZeroGPU or
+  another non-cloud-API path that satisfies that bonus.
 
 ## Project Structure
 
@@ -33,25 +42,25 @@ annotated technical cutaway animation.
   GitHub `main` to an existing Hugging Face Space.
 - `requirements.txt` - Python dependencies for the Gradio Space and Modal
   scaffold.
-- `app.py` - Hugging Face Space entry point; launches the Gradio app.
+- `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.
 - `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_threejs`
+  placeholder plus experimental llama.cpp `analyze_image` / `generate_scene`
   web endpoints.
 - `scripts/verify_runtime_assets.py` - Hugging Face metadata preflight for the
   selected GGUF quant and `mmproj` file.
 - `snap2sim/__init__.py` - package marker.
 - `snap2sim/backend.py` - backend config, local placeholder inference, Modal
   HTTP client, and image base64 encoding.
-- `snap2sim/fallback_scene.py` - themed animated SVG/CSS fallback shown when
-  generated Three.js is unavailable.
-- `snap2sim/prompts.py` - prompt templates for the vision analysis and Three.js
-  code-generation steps.
+- `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/schema.py` - structured JSON schema plus a sample mechanism payload.
-- `snap2sim/three_scene.py` - deterministic Three.js scene generation from a
-  validated mechanism payload.
-- `snap2sim/ui.py` - Gradio Blocks UI, blueprint field-manual CSS theme, and
-  pipeline orchestration.
 
 ## What Has Been Done
 
@@ -88,8 +97,8 @@ annotated technical cutaway animation.
   HTML documents.
 - Added a local coercion fallback for verbose/partial model JSON so the
   analysis endpoint does not launch a second slow repair generation.
-- Added experimental `analyze_image_llamacpp` and `generate_threejs_llamacpp`
-  Modal GPU endpoints. They are not wired into the Gradio app by default; point
+- Added experimental `analyze_image_llamacpp` and scene-generation Modal GPU
+  endpoints. They are not wired into the Gradio app by default; point
   `MODAL_ANALYZE_URL` / `MODAL_GENERATE_URL` at them only after the smoke test
   passes.
 - Fixed Modal packaging for local `snap2sim` imports by adding
@@ -102,7 +111,8 @@ annotated technical cutaway animation.
 - Deployed `modal_app.py` to Modal at
   `https://modal.com/apps/bigstonks1/main/deployed/snap2sim-inside-the-machine`.
 - Production endpoint checks passed for `runtime_probe`,
-  `analyze_image_llamacpp`, and deterministic `generate_threejs`.
+  `analyze_image_llamacpp`, and deterministic scene generation before the
+  current endpoint rename.
 - Modal web endpoints are secured with `Authorization: Bearer
   SNAP2SIM_API_TOKEN`; the token lives in Modal secret `snap2sim-api-auth` and
   Hugging Face Space secret `SNAP2SIM_API_TOKEN`.
@@ -126,6 +136,17 @@ annotated technical cutaway animation.
   Space sync on pushes to `main`. The workflow targets `jasondo111/Snap2Sim`
   and requires GitHub secret `HF_TOKEN`.
 - User reported the GitHub Actions `HF_TOKEN` secret has been added.
+- PR #1 was merged to `main`. The first GitHub-to-HF sync run reached the final
+  push step but failed with Hugging Face HTTP `429`; the workflow was updated
+  to retry that final push with bounded backoff.
+- The next GitHub Actions sync run succeeded:
+  `https://github.com/Bigstonks1/Snap2Sim/actions/runs/27487136019`.
+- Hugging Face Space `jasondo111/Snap2Sim` later reported SHA
+  `bfe49606478d6e922b0f973409fa3433f9d9ed9d`, matching GitHub `main`, after
+  the final handoff-note sync.
+- `PROMPT.md` was updated with a new critical path: `gradio.Server`,
+  `index.html`, A-Frame model scene generation, `generate_scene` naming, and a
+  deterministic Three.js fallback in browser JS.
 - Documented GitHub as the source of truth:
   `https://github.com/Bigstonks1/Snap2Sim`. Do not edit files directly on the
   Hugging Face Space; they will be overwritten by the sync workflow.
@@ -133,15 +154,35 @@ annotated technical cutaway animation.
   assistance from OpenAI Codex.
 - Updated `README.md` with local run instructions, runtime preflight, Modal
   deployment path, and the current runtime decision.
+- Rewrote `app.py` as a `gradio.Server` app with `/`, `/analyze_image`, and
+  `/generate_scene` routes.
+- Added `index.html` with upload orchestration, analysis readout, A-Frame scene
+  injection, 3-second blank-scene fallback, play/pause, and deterministic
+  browser-side Three.js fallback.
+- Renamed active backend and Modal scene generation paths to `generate_scene`.
+- Updated scene-generation prompts and parsing for `<a-scene>...</a-scene>`
+  output.
+- Deleted the legacy Gradio Blocks UI, Python iframe Three.js generator, and
+  SVG fallback modules.
+- Local verification passed with FastAPI `TestClient`: `/` returned the HTML
+  shell, `/analyze_image` returned the placeholder analysis, and
+  `/generate_scene` returned an `<a-scene>` block.
 
 ## Next Work
 
-- Point the Gradio app at `analyze_image_llamacpp` for analysis and the
-  deterministic `generate_threejs` endpoint for scene rendering.
+- Deploy the current branch through GitHub-to-HF sync, keep the Space private,
+  and confirm the private Space loads the trusted `index.html` shell.
+- Update Space/Modal endpoint variables if needed so `MODAL_GENERATE_URL`
+  points at the deployed `generate_scene` endpoint, then verify
+  `/analyze_image` and `/generate_scene` with the secured bearer-token flow.
+- Run an end-to-end private Space check with a real image: upload ->
+  `/analyze_image` -> panel population -> `/generate_scene` -> A-Frame render
+  or deterministic Three.js fallback.
+- Optional polish only after private deployment verification: component
+  watermark, noise texture, vignette, then scan-line reveal refinements.
 - Keep the Hugging Face Space private until the user explicitly approves making
   it public for submission.
-- Commit and push the workflow to GitHub `main`, then verify the GitHub Actions
-  sync run succeeds.
-- If Three.js model generation is too brittle, keep using the deterministic
-  local scene generator for the demo while still using Nemotron for analysis.
-- Document final submission links and bonus claims.
+- Keep the README opening hook intact: "You find a small metal cylinder at a
+  flea market. What is it? How does it work inside?" After implementation,
+  expand README with the updated model stack, rendering-stack rationale, and
+  bonus quest claims from `PROMPT.md`.

PROMPT.md

@@ -1,185 +1,343 @@
-PROJECT: "Inside the Machine" — AI-powered teardown visualizer for the
-Build Small Hackathon (Backyard AI track, huggingface.co/build-small-hackathon)
-
-GOAL
-Build a Gradio app, deployed as a Hugging Face Space, that takes a photo of
-a hardware component (e.g. a gear, valve, hinge, pump, lock, engine part)
-and produces an animated 3D visualization showing how that component works
-internally at a finer-grained scale than the photo shows — i.e. "open it up
-and show me the moving parts and the physics/mechanism."
-
-HARD CONSTRAINTS
-- Total model parameters across the entire pipeline must be ≤ 32B.
-- Must be a Gradio app, hosted as a Hugging Face Space.
-- Prefer local/open-weight models (target the "Off the Grid" bonus: no
-  cloud APIs at inference time, where deployment allows).
-
-MODEL STACK
-Primary model: NVIDIA Nemotron 3 Nano Omni (30B-A3B, MoE, ~3B active
-params), used for both the vision-understanding step AND the Three.js
-code generation step (two prompts/turns against the same model). This
-targets the NVIDIA Nemotron Quest sponsor award and stays comfortably
-under the 32B cap as a single model.
-
-Fallback split pipeline (use only if the primary path's code-gen quality
-is too weak, or if the multimodal runtime issue below can't be resolved):
-- NVIDIA Nemotron Nano V2 VL (12B) for image understanding/analysis.
-- Qwen2.5-Coder-14B for Three.js/animation code generation.
-- Total ~26B, still leaves headroom and still qualifies for the Nemotron
-  Quest award via the vision step.
-
-MODEL RUNTIME
-- Primary path (targets "Llama Champion" bonus): use
-  unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF via llama.cpp.
-  Start with a mid-size quant (e.g. UD-Q4_K_M, ~24 GB) for quality, and
-  have a smaller quant (e.g. UD-IQ2_M, ~18.5 GB) ready as a fallback for
-  constrained hardware.
-- IMPORTANT — verify multimodal support first: as a setup/diagnostic step,
-  confirm whether this GGUF repo includes a vision-encoder ("mmproj") file
-  for the CRADIO v4-H encoder, and whether llama.cpp's current build
-  actually accepts image input for this architecture (nemotron_h_moe).
-  Multimodal GGUF conversions often ship the LLM only, with vision support
-  lagging behind.
-  - If image input works end-to-end via llama.cpp: use this single model
-    for both the vision-analysis step and the Three.js code-gen step —
-    this is the ideal "Llama Champion" + Nemotron Quest combo.
-  - If image input is NOT yet supported in the GGUF/llama.cpp path: use
-    the NVFP4 safetensors checkpoint (nvidia/Nemotron-3-Nano-Omni-30B-A3B-
-    Reasoning-NVFP4, ~20.9 GB) via vLLM or transformers for the vision-
-    analysis step only, and use the GGUF + llama.cpp build for the
-    Three.js code-gen step (text-only, so GGUF support is solid). Note
-    in the README that "Llama Champion" applies to the code-gen stage.
-- Either way, total parameters stay at ~31B (single model), comfortably
-  under the 32B cap, and the project remains eligible for the NVIDIA
-  Nemotron Quest award.
-
-DEPLOYMENT ARCHITECTURE — two-tier with Modal
-- Tier 1 (frontend): the Gradio app, hosted as a HF Space on the standard
-  CPU tier. Handles UI, image upload, calling the inference backend, and
-  rendering the returned JSON + Three.js HTML.
-- Tier 2 (inference backend): a Modal app exposing two functions as web
-  endpoints, running on a Modal GPU container:
-  - analyze_image(image) -> structured JSON (vision step, per the
-    pipeline below)
-  - generate_threejs(json) -> Three.js scene HTML/JS (code-gen step)
-  Both load Nemotron 3 Nano Omni once at container start (use a Modal
-  Volume to cache model weights across cold starts so they aren't
-  re-downloaded every time). Use whichever runtime (llama.cpp/GGUF or
-  vLLM/NVFP4) was determined in the MODEL RUNTIME verification step.
-- The Gradio app calls these endpoints over HTTP (e.g. via `requests`),
-  passing the image as base64 and receiving JSON/HTML back.
-- Make the inference backend swappable via a config flag (e.g.
-  INFERENCE_BACKEND=modal | zerogpu | local), so the same Gradio code can
-  run against:
-  - a Modal endpoint (primary path — generous credits, no VRAM
-    constraints, targets the Modal Award)
-  - HF Spaces ZeroGPU (alternative — model loads inside the Space itself
-    on an A10G; try the smallest GGUF quant here)
-  - a local GPU (for development/testing)
-- Surface Modal cold-start latency in the UI — e.g. a "WAKING THE
-  WORKSHOP..." loading message in the established visual theme, since
-  cold starts on a 30B model can take tens of seconds.
-- README must state which backend the submitted Space actually uses, and
-  adjust bonus-quest claims accordingly: if Modal is the deployed backend,
-  "Off the Grid" is not claimed (inference happens on Modal's cloud GPUs),
-  but "Llama Champion", "Nemotron Quest", and the Modal Award still apply.
-  If ZeroGPU ends up sufficient, "Off the Grid" can additionally be claimed.
-
-PIPELINE / APPLICATION FLOW
-1. User uploads a photo of a hardware component via gr.Image.
-2. Vision step (Nemotron VL): identify the component, enumerate its
-   internal parts, and describe its operating mechanism in structured
-   terms — e.g. part names, how each part moves (rotate/translate/
-   oscillate), axes/pivots, sequence of motion, and what triggers it
-   (e.g. "input shaft rotates → cam lobe pushes follower → valve opens").
-   Output this as structured JSON (part list with geometry hints: shape,
-   approximate size/position, motion type, motion parameters).
-3. Code-gen step: feed that JSON into the second prompt/model with
-   instructions to generate a single self-contained Three.js scene (HTML
-   + inline JS/CSS) that:
-   - builds simple primitive-based 3D representations of each part
-     (boxes, cylinders, gears via extruded shapes, etc.)
-   - animates them according to the described motion (rotation speed,
-     translation range, timing/sequence)
-   - includes basic camera controls (OrbitControls) and a play/pause toggle
-   - includes on-screen labels for each part
-4. Gradio renders the generated HTML via gr.HTML (sandboxed iframe).
-5. Below the visualization, display the structured explanation text from
-   step 2 (plain-language "how it works" writeup) so the app is useful
-   even if the 3D fails to render.
-
-VISUAL DESIGN DIRECTION — "Technical Cutaway / Field Manual" (Off-Brand bonus)
-Commit fully to this aesthetic; do not fall back to default Gradio styling.
-
-- Concept: the app should feel like a page from a vintage engineering
-  service manual or a reverse-engineering field notebook — the kind of
-  diagram you'd find annotating a cutaway drawing of an engine.
-- Theme: dark "blueprint" canvas as the dominant surface — deep navy/
-  charcoal background (not pure black), with fine 1px grid lines at low
-  opacity to evoke graph/blueprint paper.
-- Color system (define as CSS variables, used consistently):
-  - Background: deep charcoal-navy (e.g. #14181F)
-  - Primary accent: warm amber/safety-orange (e.g. #E8A33D) for
-    annotations, active states, and the "how it works" highlights
-  - Secondary accent: cool cyan (e.g. #5FD4D0) for part labels and
-    motion-path indicators in the 3D scene
-  - Text: off-white / warm gray, never pure white
-- Typography: pair a condensed, slightly industrial display/grotesk font
-  (e.g. for headings/labels — something like a stencil-adjacent or
-  technical condensed sans) with a monospace font (e.g. for the part
-  list, JSON-derived data, and annotations) — avoid Inter, Roboto, Arial,
-  and system-default fonts entirely.
-- Layout: two-pane, asymmetric split (3D viewport larger/left, analysis
-  panel narrower/right or as an overlay drawer). Part labels in the 3D
-  scene should look like annotation callouts (thin leader lines + small
-  monospace tags), echoing real exploded-diagram conventions.
-- Motion: one signature moment — when the model finishes analysis and
-  the 3D scene loads, animate a "power-on" reveal (e.g. parts fade/slide
-  into place sequentially, or a scanning-line sweep across the blueprint
-  grid before the model appears). Avoid scattered micro-animations
-  elsewhere; spend the motion budget on this one moment.
-- Texture/atmosphere: subtle grid-paper background, faint scanline or
-  vignette effect on the canvas edges — restrained, not noisy.
-- Loading states should reinforce the theme (e.g. "ANALYZING ASSEMBLY...",
-  "RENDERING CUTAWAY...", "WAKING THE WORKSHOP...") in the monospace font
-  rather than generic spinners.
-
-UI / UX REQUIREMENTS
-- Clean two-pane layout per the design direction above: 3D visualization
-  + part-by-part "how it works" panel.
-- Loading states for both inference steps (vision analysis can be slow,
-  Modal cold starts add latency), styled per the theme above.
-- Graceful fallback: if Three.js code generation fails or errors, show
-  the textual explanation plus a simple 2D animated SVG/CSS fallback
-  instead of a blank pane — keep this fallback in the same visual theme.
-- Investigate gr.Server if needed to achieve full styling control beyond
-  what gr.HTML / custom CSS in Blocks allows.
-
-DELIVERABLES
-- Working Gradio app code (app.py + requirements.txt) ready to push to a
-  Hugging Face Space under the build-small-hackathon org.
-- Modal app code (modal_app.py or similar) implementing the two inference
-  endpoints described above.
-- README explaining: the problem this solves and for whom (Backyard AI
-  track requires a real person/use case — e.g. a hobbyist mechanic, a
-  shop teacher, a repair-cafe volunteer who wants to explain how parts
-  work to customers/students), the model stack and parameter count
-  (must total ≤32B, state the exact breakdown), the deployment
-  architecture, and which bonus quests/sponsor awards are targeted
-  (Llama Champion, Off-Brand, NVIDIA Nemotron Quest, Modal Award, Field
-  Notes, and "Off the Grid" if applicable to the final deployment).
-- Keep code modular: separate files/functions for (1) vision analysis,
-  (2) code generation, (3) Gradio UI/styling, (4) inference backend
-  client/config, so each piece can be swapped or debugged independently.
-
-START by:
-1. Verifying the llama.cpp multimodal support question above for the
-   Nemotron 3 Nano Omni GGUF — this determines the runtime path for the
-   rest of the build.
-2. Scaffolding the Modal app with the two inference endpoints (using
-   placeholder/echo logic initially), and the Gradio app structure with
-   the backend-config flag and CSS theme/variables for the visual design
-   direction above.
-3. Designing the JSON schema for step 2 of the pipeline — this is the
-   critical interface between the vision and code-gen steps.
-4. Iterating on prompt templates for steps 2 and 3.
+# Snap2Sim — "Inside the Machine"
+**Build Small Hackathon** · Backyard AI Track · [huggingface.co/build-small-hackathon](https://huggingface.co/build-small-hackathon)
+
+---
+
+## Goal
+
+Build a Gradio app deployed as a Hugging Face Space that takes a photo of a hardware component (gear, valve, pump, lock, engine part, etc.) and produces an animated 3D visualization showing how that component works internally — "open it up and show me the moving parts and the mechanism."
+
+---
+
+## Hard Constraints
+
+- Total model parameters across the entire pipeline **≤ 32B**
+- Must be a **Gradio app** hosted as a **Hugging Face Space**
+- No cloud AI APIs at inference time where possible (targets "Off the Grid" bonus)
+- **Plain HTML/CSS/JS frontend** — no React, no build step, no bundler
+
+---
+
+## Target User — The Curious Tinkerer / Maker
+
+Someone who pulls apart old electronics, finds a mystery component at a thrift store or salvage yard, or cracks open a broken appliance wondering: *"what does this actually do and how does it work inside?"* Not an engineer — a curious, hands-on person who learns by taking things apart.
+
+> **README must open with:** *"You find a small metal cylinder at a flea market. What is it? How does it work inside?"* — before any technical description.
+
+---
+
+## Current State (June 13, 2026)
+
+Scaffold exists at [github.com/Bigstonks1/Snap2Sim](https://github.com/Bigstonks1/Snap2Sim), synced to HF Space `jasondo111/Snap2Sim` (private, keep private until user approves).
+
+**Confirmed working:**
+- Modal deployment: `snap2sim-inside-the-machine` (bigstonks1 workspace)
+- `smoke_test_llamacpp_image` → `"ok": true` for `UD-Q4_K_M` + `mmproj-F16.gguf`
+- `analyze_image_llamacpp` and scene-generation Modal endpoints deployed
+- GitHub → HF Space sync workflow live and passing
+- Local app code now uses `gradio.Server` plus a trusted `index.html`
+
+**Primary remaining tasks:**
+1. Deploy the current branch through GitHub → HF sync
+2. Confirm the private Space loads the trusted `index.html`
+3. Confirm `/analyze_image` and `/generate_scene` respond through the secured
+   Modal bearer-token flow
+
+---
+
+## Model Stack
+
+**Primary model:** NVIDIA Nemotron 3 Nano Omni (30B-A3B, MoE, ~3B active params)
+Used for both vision analysis and A-Frame scene generation (two prompt turns, same model). Targets the **NVIDIA Nemotron Quest** sponsor award. ~31B total — under the 32B cap.
+
+### GGUF Path (confirmed working)
+| Setting | Value |
+|---|---|
+| Repo | `unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF` |
+| Primary quant | `UD-Q4_K_M` (~24 GB) + `mmproj-F16.gguf` |
+| Fallback quant | `UD-IQ2_M` (~18.5 GB) |
+| Runtime | `llama-mtmd-cli` via llama.cpp on Modal GPU |
+
+### Fallback Split Pipeline
+Only use if primary model code-gen quality is too weak:
+- **Vision:** NVIDIA Nemotron Nano V2 VL (12B)
+- **Scene gen:** Qwen2.5-Coder-14B
+- Total ~26B · still qualifies for Nemotron Quest
+
+---
+
+## Model Runtime
+
+- Inference via **llama.cpp / GGUF** → targets **"Llama Champion"** bonus
+- Modal GPU endpoints called over HTTP with Bearer token auth (`SNAP2SIM_API_TOKEN`)
+- Backend swappable via `INFERENCE_BACKEND=modal | zerogpu | local`
+- **If Modal deployed:** "Off the Grid" not claimed, but Llama Champion + Nemotron Quest + Modal Award all apply
+- **If ZeroGPU sufficient:** "Off the Grid" additionally claimable
+
+---
+
+## Deployment Architecture
+
+```
+[HF Space — CPU tier]              [Modal — GPU tier]
+  gradio.Server                      analyze_image_llamacpp
+  @app.get("/") → index.html    ←→   generate_scene
+  @app.api() → /analyze_image        (weights cached in Modal Volume)
+  @app.api() → /generate_scene
+```
+
+- Gradio app calls Modal endpoints over HTTP via `requests`, image passed as base64
+- Modal cold starts on 30B model can take tens of seconds → show `"WAKING THE WORKSHOP..."` loading state
+
+---
+
+## Architectural Shift — `gr.Blocks` → `gradio.Server`
+
+> **This is the core change. Do not skip or partially implement it.**
+
+### Why
+`gr.HTML` strips `<script>` tags for security and HF Spaces CSP blocks external CDN imports in `js_on_load`. Any WebGL/Three.js/A-Frame output piped through `gr.HTML` will fail on the live Space — scripts get stripped, nothing renders. This is a confirmed, known issue.
+
+### How `gradio.Server` Fixes It
+`gradio.Server` extends FastAPI. `@app.get("/")` serves `index.html` as a first-class trusted FastAPI response — the browser receives a full page with no stripping, no sandboxing, no CSP conflicts from Gradio's component system. A-Frame and Three.js CDN scripts load normally.
+
+```python
+from gradio import Server
+
+app = Server()
+
+@app.get("/")
+async def homepage():
+    with open("index.html") as f:
+        return HTMLResponse(f.read())
+
+@app.api(name="analyze_image")
+def analyze_image(image_b64: str) -> dict:
+    return backend.run_analysis(image_b64)  # calls Modal or local placeholder
+
+@app.api(name="generate_scene")
+def generate_scene(mechanism_json: dict) -> str:
+    return backend.run_scene_gen(mechanism_json)  # returns A-Frame HTML string
+
+app.launch()
+```
+
+### What to Change in the Scaffold
+| File | Action |
+|---|---|
+| `app.py` | `gradio.Server` app serving `index.html` and API routes |
+| `index.html` | Trusted HTML/CSS/JS shell with pipeline orchestration |
+| `modal_app.py` | `generate_scene` endpoints and A-Frame prompt |
+| `snap2sim/backend.py` | `generate_scene` backend method |
+| `snap2sim/prompts.py` | A-Frame scene-generation prompt |
+| `snap2sim/aframe_scene.py` | Deterministic A-Frame placeholder scene |
+
+---
+
+## Rendering Stack — Two Layers
+
+### Layer 1 — Model-Generated Scene: A-Frame (declarative HTML)
+
+A-Frame is a web framework built on Three.js that uses declarative HTML tags for 3D scenes. The model outputs HTML, not JavaScript — far more reliable for LLM generation.
+
+**Why A-Frame for model output:**
+- LLMs generate HTML tags far more reliably than imperative JS
+- Injected via `innerHTML`, not `eval()` — no script execution risk
+- A-Frame runtime (already loaded in `<head>`) renders injected tags automatically
+- Built-in `animation` attribute handles motion without JS animation loops
+- Camera, lighting, and sky added automatically — less boilerplate to get wrong
+
+**Loading A-Frame in `index.html`:**
+```html
+<head>
+  <script src="https://aframe.io/releases/1.6.0/aframe.min.js"></script>
+</head>
+```
+
+> **CDN fallback:** If HF Spaces blocks `aframe.io`, vendor the minified A-Frame JS (~1.1MB) as a static file served via `gradio.Server`'s FastAPI static file mounting.
+
+**Injecting model output:**
+```javascript
+document.getElementById('viewport').innerHTML = modelGeneratedAframeHTML;
+// A-Frame runtime picks up the new <a-scene> tags automatically
+```
+
+**Example of what the model should output:**
+```html
+<a-scene>
+  <a-sky color="#0F1318"></a-sky>
+  <a-cylinder color="#E8A33D" radius="0.3" height="1" position="0 1 -3"
+    animation="property: rotation; to: 0 360 0; loop: true; dur: 2000; easing: linear">
+  </a-cylinder>
+  <a-box color="#5FD4D0" position="0.8 0.5 -3"
+    animation="property: position; to: 0.8 1 -3; dir: alternate; loop: true; dur: 1000">
+  </a-box>
+  <a-text value="Drive Shaft" position="0 2 -3" color="#5FD4D0" scale="0.5 0.5 0.5">
+  </a-text>
+</a-scene>
+```
+
+**Prompt engineering for `generate_scene` endpoint:**
+- Instruct the model to output **only** the `<a-scene>...</a-scene>` block — no preamble, no markdown fences, no explanation
+- A-Frame primitives to use: `<a-box>`, `<a-cylinder>`, `<a-sphere>`, `<a-torus>`, `<a-cone>`, `<a-entity>`
+- Animation format: `animation="property: rotation; to: 0 360 0; loop: true; dur: 2000; easing: linear"`
+- Keep scenes to **3–6 parts maximum** for clarity
+- Set `<a-sky color="#0F1318">` to match the page background
+
+### Layer 2 — Deterministic Fallback: Three.js (human-written)
+
+If A-Frame output is empty, malformed, or renders blank after 3 seconds, immediately swap to `buildDeterministicScene(json)` — a JS function that reads the mechanism JSON and builds a reliable Three.js scene from geometric primitives.
+
+```javascript
+function buildDeterministicScene(mechanismJson) {
+  // Human-written. Always works given valid JSON.
+  // Uses: BoxGeometry, CylinderGeometry, TorusGeometry per part shape
+  // Applies rotation/translation per motion_type
+  // Adds OrbitControls, annotation labels
+  // The viewport must never be blank or show an error
+}
+```
+
+> Load Three.js in `index.html` alongside A-Frame:
+> ```html
+> <script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js"></script>
+> ```
+
+---
+
+## Pipeline / Application Flow
+
+```
+1. User uploads photo
+        ↓
+2. Frontend encodes as base64 → calls /analyze_image (Gradio JS client)
+        ↓
+3. Nemotron vision step → structured JSON:
+   {
+     "component_name": "Solenoid Valve",
+     "parts": [
+       { "name": "Coil", "shape": "cylinder", "color": "#E8A33D",
+         "position": [0, 0, 0], "motion_type": "none", "motion_params": {} },
+       { "name": "Plunger", "shape": "cylinder", "color": "#5FD4D0",
+         "position": [0, 0.5, 0], "motion_type": "translate",
+         "motion_params": { "axis": "y", "range": 0.3, "dur": 800 } }
+     ],
+     "summary": "When current flows through the coil, it generates a magnetic
+                 field that pulls the plunger upward, opening the valve port."
+   }
+        ↓
+4. Frontend populates analysis panel (name, part list, summary)
+   → immediately calls /generate_scene with JSON
+        ↓
+5. Nemotron scene gen step → A-Frame HTML string (<a-scene>...</a-scene>)
+        ↓
+6. Frontend injects A-Frame HTML → innerHTML of #viewport
+   A-Frame runtime renders automatically
+        ↓
+7. If A-Frame blank/failed after 3s → buildDeterministicScene(json)
+   Viewport is NEVER blank
+```
+
+---
+
+## Visual Design — "Industrial Instrument Panel / Field Cutaway"
+
+> Implement the shell and CSS in Step 2. Do **not** work on `[POLISH]` items until Steps 1–4 are done.
+
+### Color System
+```css
+:root {
+  --bg:         #0F1318;
+  --bg-panel:   #161B22;
+  --bg-lift:    #1E2530;
+  --amber:      #E8A33D;
+  --amber-dim:  #7A5420;
+  --cyan:       #5FD4D0;
+  --cyan-dim:   #2A5E5C;
+  --text:       #C8C0AC;
+  --text-muted: #6B7280;
+  --grid:       rgba(255,255,255,0.04);
+}
+```
+
+### Typography
+Load from **Bunny Fonts** (not Google Fonts):
+- **Display / headings / UI labels:** `Chakra Petch` — technical, instrument-panel character
+- **Monospace / data / callouts:** `Fira Code`
+- **Never use:** Inter, Roboto, Arial, Space Grotesk, or any system font
+
+### Layout
+- Two-pane asymmetric split: **63% viewport** (left) · **37% analysis panel** (right)
+- Blueprint grid: 1px lines at `--grid` opacity, 32px spacing, on `--bg` base
+- Panel separator: 1px vertical line in `--amber-dim`
+- Upload drop zone: fills viewport · dashed 1px `--amber-dim` border (no `border-radius`) · centered `"DROP COMPONENT PHOTO"` in Chakra Petch uppercase `--text-muted` · on drag-over: border → `--amber`, text → `--amber`
+- Play/pause: minimal amber rectangle (no `border-radius`), Chakra Petch uppercase `"PAUSE"` / `"RESUME"`, controls A-Frame animation playback via JS
+
+### Loading States
+All in Chakra Petch uppercase, `--amber` color, with thin `--amber` indeterminate progress bar across viewport top:
+
+| State | Message |
+|---|---|
+| Modal cold start | `WAKING THE WORKSHOP...` |
+| Vision inference | `ANALYZING ASSEMBLY...` |
+| Scene generation | `RENDERING CUTAWAY...` |
+
+### [POLISH] — Only After Steps 1–4 Work
+Implement in this sub-order:
+
+1. **Component name watermark** — large (`clamp(4rem, 8vw, 9rem)`) Chakra Petch uppercase in `--bg-lift`, absolutely positioned bleeding across both panes from bottom-left, `z-index` below content. Populated from `component_name` in JSON.
+
+2. **Noise texture** — SVG `feTurbulence` grain at 3% opacity on viewport pane, inline `data:` URI, no external file. Makes the surface feel physical.
+
+3. **Vignette** — radial gradient overlay on viewport edges, `pointer-events: none` so it floats above the A-Frame canvas without blocking interaction.
+
+4. **Scan-line reveal** — when A-Frame scene first loads:
+   - 2px `--cyan` scan-line sweeps top→bottom over 0.7s
+   - Each A-Frame entity fades in as line passes it (`opacity 0→1`, `translateY 12px→0`, 0.35s ease-out, staggered by part index via `animation-delay`)
+   - Part labels fade in together (0.25s)
+   - Progress bar dissolves (0.2s)
+   - Total: ~1.2s · this is the signature moment
+
+---
+
+## Deliverables
+
+- `app.py` — `gradio.Server` app (~50 lines)
+- `index.html` — self-contained HTML/CSS/JS; A-Frame + Three.js from CDN; Gradio JS client from CDN
+- `snap2sim/backend.py` — `generate_scene`
+- `modal_app.py` — `generate_scene`; A-Frame prompt
+- `snap2sim/prompts.py` — updated A-Frame scene generation prompt
+- `requirements.txt` — updated if needed for `gradio.Server`
+- `README.md` — tinkerer/maker story hook → project description → model stack with exact parameter breakdown (≤32B) → rendering stack rationale → bonus quest claims:
+
+| Quest | Status |
+|---|---|
+| Llama Champion | ✅ Confirmed |
+| NVIDIA Nemotron Quest | ✅ Confirmed |
+| Off-Brand | ✅ Confirmed |
+| Modal Award | ✅ Confirmed |
+| Off the Grid | ⚡ If ZeroGPU used in final deploy |
+| Field Notes | 🎯 Stretch |
+
+---
+
+## Start Order
+
+> Follow this exactly. Do not skip ahead.
+
+### Step 1 — Critical Path
+Deploy the current `gradio.Server` + `index.html` implementation through
+GitHub → HF sync. Confirm the private Space loads and both `/analyze_image`
+and `/generate_scene` respond.
+
+### Step 2 — Make It Functional
+Build `buildDeterministicScene(json)` in JS — Three.js scene from geometric primitives, always works given valid JSON. Wire the full pipeline: upload → `/analyze_image` → populate analysis panel → `/generate_scene` → inject A-Frame HTML via `innerHTML` → fallback to `buildDeterministicScene(json)` if A-Frame fails or blanks after 3 seconds. **Confirm end-to-end with a real image and live Modal endpoints.**
+
+### Step 3 — Apply the Design Shell
+Add CSS variable system, Chakra Petch + Fira Code from Bunny Fonts, two-pane asymmetric layout, blueprint grid, loading states with progress bar, upload drop zone, panel separator. App should match the design direction above — minus `[POLISH]` items.
+
+### Step 4 — Harden
+Error handling, 3-second blank-scene timeout before fallback triggers, Modal cold-start messaging, A-Frame `<a-sky color="#0F1318">` matching page background, play/pause toggle wired to A-Frame animation playback. Verify GitHub → HF Space sync pushes cleanly and the private Space runs correctly.
+
+### Step 5 — [POLISH] Only if Time Remains
+Component name watermark → noise texture → vignette → scan-line reveal. In that order.

README.md

@@ -9,13 +9,18 @@ colorTo: yellow
 
 # Snap2Sim
 
-Inside the Machine is a Gradio app scaffold for the Build Small Hackathon
-Backyard AI track. It takes a hardware component photo, produces a structured
-mechanism analysis, and renders a technical cutaway visualization.
+You find a small metal cylinder at a flea market. What is it? How does it work
+inside?
 
-The local app still defaults to the placeholder backend, but the Modal
-llama.cpp path has been smoke-tested with the selected Nemotron GGUF and
-projector.
+Inside the Machine is a Build Small Hackathon Backyard AI project for curious
+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.
 
 ## Run Locally
 
@@ -25,7 +30,8 @@ python app.py
 ```
 
 Set `INFERENCE_BACKEND=modal`, `MODAL_ANALYZE_URL`, and `MODAL_GENERATE_URL`
-to point the Gradio app at deployed Modal endpoints.
+to point the Gradio app at deployed Modal `/analyze_image` and
+`/generate_scene` endpoints.
 
 For the deployed demo configuration, copy `.env.example` into local environment
 variables or Hugging Face Space variables. Do not put tokens in `.env.example`;
@@ -68,20 +74,60 @@ Primary references:
 - https://huggingface.co/unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF
 - https://github.com/ggml-org/llama.cpp
 
+## Model Stack and Quest Claims
+
+Primary inference uses NVIDIA Nemotron 3 Nano Omni 30B-A3B through llama.cpp
+GGUF. The model has about 30B total parameters with roughly 3B active per MoE
+token, keeping the single-model pipeline under the hackathon 32B cap.
+
+Fallback, only if the primary endpoint quality is not demo-ready, is
+NVIDIA Nemotron Nano V2 VL 12B for vision plus Qwen2.5-Coder-14B for scene
+generation, for about 26B total parameters.
+
+| Quest | Status |
+|---|---|
+| Llama Champion | Confirmed via llama.cpp / GGUF runtime |
+| NVIDIA Nemotron Quest | Confirmed via Nemotron primary model |
+| Off-Brand | Confirmed |
+| Modal Award | Confirmed via deployed Modal endpoints |
+| Off the Grid | Not claimed while inference runs on Modal |
+| Field Notes | Stretch |
+
 ## Project Structure
 
 - `.env.example` - public runtime variables for the deployed Modal demo.
 - `SECURITY.md` - public/private data handling guidance for humans and agents.
-- `app.py` - Hugging Face Space entry point.
+- `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.
 - `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/fallback_scene.py` - themed 2D fallback animation.
-- `snap2sim/prompts.py` - prompt templates for vision and Three.js generation.
+- `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/schema.py` - JSON schema and sample analysis payload.
-- `snap2sim/three_scene.py` - deterministic Three.js scene generation from the
-  validated mechanism JSON.
-- `snap2sim/ui.py` - Gradio Blocks UI and visual theme.
+
+## 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.
+
+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.
+
+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.
 
 ## Modal Deployment Path
 
@@ -113,9 +159,9 @@ 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_threejs` preserve the current HTTP contract for
+- `analyze_image` and `generate_scene` preserve the current HTTP contract for
   the Gradio app.
-- `analyze_image_llamacpp` and `generate_threejs_llamacpp` are experimental GPU
+- `analyze_image_llamacpp` and `generate_scene_llamacpp` are experimental GPU
   endpoints for the llama.cpp runtime path after the smoke test passes.
 
 Runtime environment knobs:
@@ -130,7 +176,7 @@ Runtime environment knobs:
 
 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_threejs`.
+`MODAL_GENERATE_URL` on deterministic `generate_scene`.
 
 Run the deployment preflight in this order:
 

SECURITY.md

@@ -82,6 +82,12 @@ 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
+  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 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

@@ -1,11 +1,96 @@
-"""Hugging Face Space entry point."""
+"""Hugging Face Space entry point for the trusted HTML shell."""
 
-from snap2sim.ui import build_app
+from __future__ import annotations
 
+import base64
+from io import BytesIO
+from pathlib import Path
+from typing import Any, Callable
 
-demo = build_app()
+from fastapi.responses import HTMLResponse
+from PIL import Image
 
+from snap2sim.backend import InferenceClient, Settings
+
+try:
+    from gradio import Server
+except ImportError:
+    from fastapi import FastAPI
+    import uvicorn
+
+    class Server(FastAPI):  # type: ignore[no-redef]
+        """Local compatibility shim for environments older than Gradio Server."""
+
+        def api(self, name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+            def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+                return func
+
+            return decorator
+
+        def launch(self, **kwargs: Any) -> None:
+            uvicorn.run(
+                self,
+                host=kwargs.get("server_name", "0.0.0.0"),
+                port=kwargs.get("server_port", 7860),
+            )
+
+
+app = Server()
+INDEX_PATH = Path(__file__).with_name("index.html")
+
+
+@app.get("/", response_class=HTMLResponse)
+async def homepage() -> str:
+    return INDEX_PATH.read_text(encoding="utf-8")
+
+
+@app.get("/manifest.json")
+async def manifest() -> dict[str, Any]:
+    return {
+        "name": "Snap2Sim Inside the Machine",
+        "short_name": "Snap2Sim",
+        "start_url": "/",
+        "display": "standalone",
+        "background_color": "#0F1318",
+        "theme_color": "#E8A33D",
+    }
+
+
+@app.api(name="analyze_image")
+def analyze_image_api(image_base64: str) -> dict[str, Any]:
+    return _analyze_image(image_base64)
 
-if __name__ == "__main__":
-    demo.launch()
 
+@app.post("/analyze_image")
+def analyze_image_http(payload: dict[str, Any]) -> dict[str, Any]:
+    return _analyze_image(str(payload.get("image_base64", "")))
+
+
+@app.api(name="generate_scene")
+def generate_scene_api(analysis: dict[str, Any]) -> str:
+    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 _analyze_image(image_base64: str) -> dict[str, Any]:
+    image = _decode_image(image_base64) if image_base64 else None
+    return InferenceClient(Settings()).analyze_image(image)
+
+
+def _generate_scene(analysis: dict[str, Any]) -> str:
+    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 __name__ == "__main__":
+    app.launch()

index.html

@@ -0,0 +1,808 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <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="module">
+    import { Client } from "https://cdn.jsdelivr.net/npm/@gradio/client/dist/index.min.js";
+    window.snap2simGradioClient = Client;
+  </script>
+  <style>
+    :root {
+      --bg: #0F1318;
+      --bg-panel: #161B22;
+      --bg-lift: #1E2530;
+      --amber: #E8A33D;
+      --amber-dim: #7A5420;
+      --cyan: #5FD4D0;
+      --cyan-dim: #2A5E5C;
+      --text: #C8C0AC;
+      --text-muted: #6B7280;
+      --grid: rgba(255,255,255,0.04);
+      --danger: #F07F5A;
+    }
+
+    * {
+      box-sizing: border-box;
+    }
+
+    html,
+    body {
+      width: 100%;
+      height: 100%;
+      margin: 0;
+      overflow: hidden;
+      color: var(--text);
+      background:
+        linear-gradient(var(--grid) 1px, transparent 1px),
+        linear-gradient(90deg, var(--grid) 1px, transparent 1px),
+        var(--bg);
+      background-size: 32px 32px;
+      font-family: "Chakra Petch", "Fira Code", monospace;
+    }
+
+    button,
+    input {
+      font: inherit;
+    }
+
+    .shell {
+      display: grid;
+      grid-template-columns: minmax(0, 63fr) minmax(340px, 37fr);
+      width: 100vw;
+      height: 100vh;
+    }
+
+    .viewport-pane {
+      position: relative;
+      min-width: 0;
+      overflow: hidden;
+      background:
+        radial-gradient(circle at 50% 40%, rgba(95, 212, 208, 0.06), transparent 42%),
+        var(--bg);
+    }
+
+    .viewport-pane::after {
+      content: "";
+      position: absolute;
+      inset: 0;
+      pointer-events: none;
+      background: radial-gradient(circle at center, transparent 58%, rgba(0, 0, 0, 0.36));
+      z-index: 7;
+    }
+
+    #viewport {
+      position: absolute;
+      inset: 0;
+      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;
+      z-index: 5;
+      display: grid;
+      place-items: center;
+      border: 1px dashed var(--amber-dim);
+      color: var(--text-muted);
+      background: rgba(15, 19, 24, 0.72);
+      text-transform: uppercase;
+      letter-spacing: 0;
+      font-size: clamp(1.15rem, 2vw, 2.1rem);
+      font-weight: 600;
+      transition: color 160ms ease, border-color 160ms ease, background 160ms ease;
+    }
+
+    .drop-zone.dragging {
+      color: var(--amber);
+      border-color: var(--amber);
+      background: rgba(122, 84, 32, 0.16);
+    }
+
+    .drop-zone.hidden {
+      display: none;
+    }
+
+    .scan-line {
+      position: absolute;
+      left: 0;
+      right: 0;
+      top: -2px;
+      z-index: 8;
+      height: 2px;
+      opacity: 0;
+      background: var(--cyan);
+      box-shadow: 0 0 18px rgba(95, 212, 208, 0.8);
+      pointer-events: none;
+    }
+
+    .scan-line.active {
+      animation: scan 700ms ease-out;
+    }
+
+    .progress {
+      position: absolute;
+      left: 0;
+      right: 0;
+      top: 0;
+      z-index: 9;
+      height: 2px;
+      overflow: hidden;
+      opacity: 0;
+      background: rgba(122, 84, 32, 0.35);
+      transition: opacity 180ms ease;
+    }
+
+    .progress.active {
+      opacity: 1;
+    }
+
+    .progress::before {
+      content: "";
+      position: absolute;
+      top: 0;
+      bottom: 0;
+      width: 34%;
+      background: var(--amber);
+      animation: loading 1050ms linear infinite;
+    }
+
+    .toolbar {
+      position: absolute;
+      left: 18px;
+      top: 18px;
+      z-index: 10;
+      display: flex;
+      gap: 8px;
+    }
+
+    .tool-button {
+      min-width: 82px;
+      min-height: 34px;
+      border: 1px solid var(--amber-dim);
+      border-radius: 0;
+      color: var(--amber);
+      background: rgba(15, 19, 24, 0.86);
+      text-transform: uppercase;
+      letter-spacing: 0;
+      cursor: pointer;
+    }
+
+    .tool-button:hover,
+    .tool-button:focus-visible {
+      border-color: var(--amber);
+      outline: none;
+    }
+
+    .tool-button[disabled] {
+      color: var(--text-muted);
+      border-color: var(--cyan-dim);
+      cursor: default;
+    }
+
+    .panel {
+      min-width: 0;
+      overflow: auto;
+      border-left: 1px solid var(--amber-dim);
+      background: linear-gradient(180deg, rgba(30, 37, 48, 0.92), var(--bg-panel));
+    }
+
+    .panel-inner {
+      min-height: 100%;
+      padding: 24px;
+      display: grid;
+      grid-template-rows: auto auto 1fr auto;
+      gap: 22px;
+    }
+
+    .brand {
+      display: grid;
+      gap: 8px;
+      border-bottom: 1px solid rgba(122, 84, 32, 0.7);
+      padding-bottom: 18px;
+    }
+
+    .kicker,
+    .label {
+      color: var(--amber);
+      font-size: 0.78rem;
+      font-weight: 600;
+      text-transform: uppercase;
+    }
+
+    h1 {
+      margin: 0;
+      color: var(--text);
+      font-size: clamp(2rem, 4vw, 4.4rem);
+      line-height: 0.9;
+      font-weight: 700;
+      letter-spacing: 0;
+      text-transform: uppercase;
+    }
+
+    .status {
+      min-height: 24px;
+      color: var(--amber);
+      font-size: 0.92rem;
+      font-weight: 600;
+      text-transform: uppercase;
+    }
+
+    .status.error {
+      color: var(--danger);
+    }
+
+    .readout {
+      display: grid;
+      gap: 18px;
+    }
+
+    .metric-row {
+      display: grid;
+      grid-template-columns: 1fr auto;
+      gap: 16px;
+      align-items: baseline;
+      border-bottom: 1px solid rgba(95, 212, 208, 0.16);
+      padding-bottom: 10px;
+    }
+
+    .component {
+      color: var(--cyan);
+      font-size: clamp(1.4rem, 2.2vw, 2.4rem);
+      font-weight: 700;
+      line-height: 1;
+      text-transform: uppercase;
+    }
+
+    .confidence {
+      color: var(--amber);
+      font-family: "Fira Code", monospace;
+      font-size: 0.95rem;
+    }
+
+    .summary,
+    .trigger,
+    .sequence,
+    .parts {
+      margin: 0;
+      color: var(--text);
+      font-size: 0.98rem;
+      line-height: 1.5;
+    }
+
+    .trigger {
+      color: var(--text-muted);
+    }
+
+    .sequence,
+    .parts {
+      display: grid;
+      gap: 8px;
+      padding: 0;
+      list-style: none;
+    }
+
+    .sequence li,
+    .parts li {
+      border-left: 1px solid var(--cyan-dim);
+      padding-left: 10px;
+    }
+
+    .parts strong {
+      display: block;
+      color: var(--cyan);
+      font-weight: 600;
+      text-transform: uppercase;
+    }
+
+    .json-box {
+      max-height: 240px;
+      overflow: auto;
+      margin: 0;
+      border-top: 1px solid rgba(122, 84, 32, 0.7);
+      padding-top: 14px;
+      color: var(--text-muted);
+      font: 0.78rem/1.45 "Fira Code", monospace;
+      white-space: pre-wrap;
+    }
+
+    .fallback-stage,
+    .scene-mount,
+    .label-layer {
+      position: absolute;
+      inset: 0;
+    }
+
+    .scene-label {
+      position: absolute;
+      max-width: min(180px, 34vw);
+      transform: translate(-50%, -50%);
+      border-left: 1px solid var(--cyan);
+      padding: 4px 0 4px 8px;
+      color: var(--cyan);
+      background: rgba(15, 19, 24, 0.72);
+      font: 0.72rem/1.2 "Fira Code", monospace;
+      text-transform: uppercase;
+      pointer-events: none;
+    }
+
+    @keyframes loading {
+      from { transform: translateX(-100%); }
+      to { transform: translateX(300%); }
+    }
+
+    @keyframes scan {
+      0% { transform: translateY(0); opacity: 0; }
+      12%, 75% { opacity: 1; }
+      100% { transform: translateY(100vh); opacity: 0; }
+    }
+
+    @media (max-width: 860px) {
+      body {
+        overflow: auto;
+      }
+
+      .shell {
+        grid-template-columns: 1fr;
+        grid-template-rows: minmax(420px, 62vh) auto;
+        min-height: 100vh;
+        height: auto;
+      }
+
+      .panel {
+        border-left: 0;
+        border-top: 1px solid var(--amber-dim);
+      }
+    }
+  </style>
+</head>
+<body>
+  <main class="shell">
+    <section class="viewport-pane" aria-label="Cutaway viewport">
+      <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>
+      </div>
+      <div id="viewport"></div>
+      <label id="dropZone" class="drop-zone" for="fileInput">Drop component photo</label>
+      <div id="scanLine" class="scan-line"></div>
+      <input id="fileInput" type="file" accept="image/*" hidden>
+    </section>
+
+    <aside class="panel">
+      <div class="panel-inner">
+        <header class="brand">
+          <div class="kicker">Snap2Sim</div>
+          <h1>Inside the Machine</h1>
+          <div id="status" class="status">Standby</div>
+        </header>
+
+        <section class="readout">
+          <div class="metric-row">
+            <div id="component" class="component">Awaiting Photo</div>
+            <div id="confidence" class="confidence">--</div>
+          </div>
+          <p id="summary" class="summary"></p>
+          <p id="trigger" class="trigger"></p>
+        </section>
+
+        <section class="readout">
+          <div>
+            <div class="label">Motion Sequence</div>
+            <ol id="sequence" class="sequence"></ol>
+          </div>
+          <div>
+            <div class="label">Parts</div>
+            <ul id="parts" class="parts"></ul>
+          </div>
+        </section>
+
+        <pre id="rawJson" class="json-box">{}</pre>
+      </div>
+    </aside>
+  </main>
+
+  <script>
+    const fileInput = document.getElementById("fileInput");
+    const uploadButton = document.getElementById("uploadButton");
+    const playButton = document.getElementById("playButton");
+    const dropZone = document.getElementById("dropZone");
+    const viewport = document.getElementById("viewport");
+    const progress = document.getElementById("progress");
+    const scanLine = document.getElementById("scanLine");
+    const statusEl = document.getElementById("status");
+    const componentEl = document.getElementById("component");
+    const confidenceEl = document.getElementById("confidence");
+    const summaryEl = document.getElementById("summary");
+    const triggerEl = document.getElementById("trigger");
+    const sequenceEl = document.getElementById("sequence");
+    const partsEl = document.getElementById("parts");
+    const rawJsonEl = document.getElementById("rawJson");
+
+    let activeMode = "idle";
+    let paused = false;
+    let coldStartTimer = 0;
+    let fallbackRuntime = null;
+
+    uploadButton.addEventListener("click", () => fileInput.click());
+    fileInput.addEventListener("change", () => {
+      const file = fileInput.files && fileInput.files[0];
+      if (file) runPipeline(file);
+    });
+
+    for (const eventName of ["dragenter", "dragover"]) {
+      dropZone.addEventListener(eventName, (event) => {
+        event.preventDefault();
+        dropZone.classList.add("dragging");
+      });
+    }
+
+    for (const eventName of ["dragleave", "drop"]) {
+      dropZone.addEventListener(eventName, (event) => {
+        event.preventDefault();
+        dropZone.classList.remove("dragging");
+      });
+    }
+
+    dropZone.addEventListener("drop", (event) => {
+      const file = event.dataTransfer.files && event.dataTransfer.files[0];
+      if (file) runPipeline(file);
+    });
+
+    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) {
+      resetScene();
+      setBusy(true);
+      setStatus("ANALYZING ASSEMBLY...");
+      coldStartTimer = window.setTimeout(() => setStatus("WAKING THE WORKSHOP..."), 6500);
+
+      try {
+        const imageBase64 = await fileToDataUrl(file);
+        const analysis = await postJson("/analyze_image", { image_base64: imageBase64 });
+        window.clearTimeout(coldStartTimer);
+        populateAnalysis(analysis);
+
+        setStatus("RENDERING CUTAWAY...");
+        const sceneResponse = await postJson("/generate_scene", { analysis });
+        const sceneHtml = typeof sceneResponse === "string" ? sceneResponse : sceneResponse.html;
+        renderAframe(sceneHtml, analysis);
+      } catch (error) {
+        window.clearTimeout(coldStartTimer);
+        setStatus(error.message || String(error), true);
+        if (window.lastAnalysis) buildDeterministicScene(window.lastAnalysis);
+      } finally {
+        setBusy(false);
+      }
+    }
+
+    function resetScene() {
+      if (fallbackRuntime && fallbackRuntime.cleanup) fallbackRuntime.cleanup();
+      fallbackRuntime = null;
+      activeMode = "idle";
+      paused = false;
+      playButton.textContent = "Pause";
+      playButton.disabled = true;
+      viewport.replaceChildren();
+      dropZone.classList.add("hidden");
+    }
+
+    function populateAnalysis(analysis) {
+      window.lastAnalysis = analysis;
+      componentEl.textContent = String(analysis.component || "Component").toUpperCase();
+      confidenceEl.textContent = typeof analysis.confidence === "number"
+        ? Math.round(analysis.confidence * 100) + "%"
+        : "--";
+      summaryEl.textContent = analysis.summary || "";
+      triggerEl.textContent = analysis.trigger ? "Trigger: " + analysis.trigger : "";
+      rawJsonEl.textContent = JSON.stringify(analysis, null, 2);
+      sequenceEl.replaceChildren(...(analysis.motion_sequence || []).map((step) => {
+        const item = document.createElement("li");
+        item.textContent = step;
+        return item;
+      }));
+      partsEl.replaceChildren(...(analysis.parts || []).map((part) => {
+        const item = document.createElement("li");
+        const name = document.createElement("strong");
+        name.textContent = part.name || part.id || "part";
+        const role = document.createElement("span");
+        role.textContent = part.role || "";
+        item.append(name, role);
+        return item;
+      }));
+    }
+
+    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);
+      if (!threeRuntime) {
+        setStatus("3D RUNTIME UNAVAILABLE", true);
+        return;
+      }
+      window.THREE = threeRuntime;
+
+      if (fallbackRuntime && fallbackRuntime.cleanup) fallbackRuntime.cleanup();
+      activeMode = "three";
+      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>';
+
+      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);
+
+      const scene = new THREE.Scene();
+      scene.fog = new THREE.Fog(0x0f1318, 8, 20);
+
+      const camera = new THREE.PerspectiveCamera(42, 1, 0.1, 100);
+      camera.position.set(5.4, 3.9, 6.2);
+
+      const controls = window.THREE.OrbitControls
+        ? new THREE.OrbitControls(camera, renderer.domElement)
+        : null;
+      if (controls) {
+        controls.enableDamping = true;
+        controls.target.set(0, 0.1, 0);
+      }
+
+      scene.add(new THREE.HemisphereLight(0x5fd4d0, 0x0f1318, 1.2));
+      const key = new THREE.DirectionalLight(0xe8a33d, 1.9);
+      key.position.set(4, 6, 5);
+      scene.add(key);
+
+      const grid = new THREE.GridHelper(8, 32, 0x2a5e5c, 0x1e2530);
+      grid.material.transparent = true;
+      grid.material.opacity = 0.75;
+      scene.add(grid);
+
+      const meshes = (analysis.parts || []).slice(0, 6).map((part, index) => {
+        const mesh = buildPartMesh(part, index);
+        const position = part.geometry && part.geometry.position || [0, 0, 0];
+        mesh.position.set(position[0], position[1], position[2]);
+        if (part.geometry && Array.isArray(part.geometry.rotation)) {
+          mesh.rotation.fromArray(part.geometry.rotation);
+        }
+        mesh.userData.basePosition = mesh.position.clone();
+        mesh.userData.baseRotation = mesh.rotation.clone();
+        mesh.userData.part = part;
+        mesh.scale.setScalar(0.001);
+        scene.add(mesh);
+        return mesh;
+      });
+
+      const clock = new THREE.Clock();
+      let frameId = 0;
+      let disposed = false;
+      fallbackRuntime = {
+        playing: true,
+        cleanup() {
+          disposed = true;
+          cancelAnimationFrame(frameId);
+          renderer.dispose();
+        }
+      };
+
+      function resize() {
+        const rect = viewport.getBoundingClientRect();
+        camera.aspect = Math.max(1, rect.width) / Math.max(1, rect.height);
+        camera.updateProjectionMatrix();
+        renderer.setSize(Math.max(1, rect.width), Math.max(1, rect.height));
+      }
+
+      function animate() {
+        if (disposed) return;
+        frameId = requestAnimationFrame(animate);
+        const elapsed = clock.getElapsedTime();
+        for (const [index, mesh] of meshes.entries()) {
+          revealMesh(mesh, elapsed, index);
+          if (fallbackRuntime.playing) applyMotion(mesh, elapsed);
+        }
+        if (controls) controls.update();
+        renderer.render(scene, camera);
+        updateLabels(camera, labelLayer, meshes);
+      }
+
+      window.addEventListener("resize", resize);
+      const originalCleanup = fallbackRuntime.cleanup;
+      fallbackRuntime.cleanup = () => {
+        window.removeEventListener("resize", resize);
+        originalCleanup();
+      };
+
+      resize();
+      animate();
+      revealScan();
+      setStatus("CUTAWAY READY");
+    }
+
+    function buildPartMesh(part, index) {
+      const geometryData = part.geometry || {};
+      const size = Array.isArray(geometryData.size) ? geometryData.size : [1, 1, 1];
+      let geometry;
+      if (geometryData.shape === "cylinder") {
+        geometry = new THREE.CylinderGeometry(size[0] / 2, size[2] / 2, size[1], 48);
+      } else if (geometryData.shape === "sphere") {
+        geometry = new THREE.SphereGeometry(Math.max(size[0], size[1], size[2]) / 2, 36, 18);
+      } else if (geometryData.shape === "rod") {
+        geometry = new THREE.CylinderGeometry(Math.max(size[0], size[1]) / 2, Math.max(size[0], size[1]) / 2, size[2], 24);
+        geometry.rotateX(Math.PI / 2);
+      } else if (geometryData.shape === "gear") {
+        geometry = gearGeometry(Math.max(size[0], size[2]) / 2, size[1], geometryData.teeth || 18);
+      } else {
+        geometry = new THREE.BoxGeometry(size[0], size[1], size[2]);
+      }
+
+      const color = colorFor(geometryData.color, index);
+      const material = new THREE.MeshStandardMaterial({
+        color,
+        metalness: 0.48,
+        roughness: 0.34,
+        emissive: color,
+        emissiveIntensity: 0.04
+      });
+      return new THREE.Mesh(geometry, material);
+    }
+
+    function gearGeometry(radius, depth, teeth) {
+      const shape = new THREE.Shape();
+      const steps = teeth * 2;
+      for (let i = 0; i <= steps; i += 1) {
+        const angle = (i / steps) * Math.PI * 2;
+        const r = radius * (i % 2 === 0 ? 1 : 0.84);
+        const x = Math.cos(angle) * r;
+        const y = Math.sin(angle) * r;
+        if (i === 0) shape.moveTo(x, y);
+        else shape.lineTo(x, y);
+      }
+      const hole = new THREE.Path();
+      hole.absarc(0, 0, radius * 0.26, 0, Math.PI * 2, true);
+      shape.holes.push(hole);
+      const geometry = new THREE.ExtrudeGeometry(shape, { depth, bevelEnabled: false });
+      geometry.center();
+      geometry.rotateX(Math.PI / 2);
+      return geometry;
+    }
+
+    function revealMesh(mesh, elapsed, index) {
+      const local = Math.max(0, Math.min(1, (elapsed - index * 0.1) / 0.55));
+      const eased = 1 - Math.pow(1 - local, 3);
+      mesh.scale.setScalar(eased);
+    }
+
+    function applyMotion(mesh, elapsed) {
+      const motion = mesh.userData.part.motion || { type: "static" };
+      const speed = Number(motion.speed || 1);
+      const phase = Number(motion.phase || 0);
+      const axis = new THREE.Vector3(...(motion.axis || [0, 1, 0])).normalize();
+      mesh.position.copy(mesh.userData.basePosition);
+      mesh.rotation.copy(mesh.userData.baseRotation);
+      if (motion.type === "rotate") {
+        mesh.rotateOnAxis(axis, elapsed * speed + phase);
+      } else if (motion.type === "oscillate") {
+        mesh.rotateOnAxis(axis, Math.sin(elapsed * speed + phase) * Number(motion.amplitude || 0.25));
+      } else if (motion.type === "translate") {
+        const range = motion.range || [-0.25, 0.25];
+        const offset = range[0] + (range[1] - range[0]) * ((Math.sin(elapsed * speed + phase) + 1) / 2);
+        mesh.position.add(axis.multiplyScalar(offset));
+      }
+    }
+
+    function updateLabels(camera, labelLayer, meshes) {
+      const rect = viewport.getBoundingClientRect();
+      labelLayer.replaceChildren();
+      for (const mesh of meshes) {
+        const projected = mesh.position.clone().project(camera);
+        if (projected.z < -1 || projected.z > 1) continue;
+        const label = document.createElement("div");
+        label.className = "scene-label";
+        label.style.left = Math.min(rect.width - 72, Math.max(72, (projected.x * 0.5 + 0.5) * rect.width)) + "px";
+        label.style.top = Math.min(rect.height - 36, Math.max(56, (-projected.y * 0.5 + 0.5) * rect.height)) + "px";
+        label.textContent = mesh.userData.part.name || mesh.userData.part.id || "part";
+        labelLayer.appendChild(label);
+      }
+    }
+
+    function colorFor(name, index) {
+      const key = String(name || "").toLowerCase();
+      if (key.includes("amber") || key.includes("orange")) return 0xe8a33d;
+      if (key.includes("cyan")) return 0x5fd4d0;
+      if (key.includes("steel")) return 0x9aa4a6;
+      return [0x5fd4d0, 0xe8a33d, 0xc8c0ac, 0x80b8ff, 0xf07f5a, 0xa7d676][index % 6];
+    }
+
+    async function postJson(url, payload) {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload)
+      });
+      if (!response.ok) {
+        let message = response.statusText || "Request failed";
+        try {
+          const data = await response.json();
+          message = data.detail || data.error || message;
+        } catch (_) {}
+        throw new Error(message);
+      }
+      return response.json();
+    }
+
+    function fileToDataUrl(file) {
+      return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onload = () => resolve(String(reader.result || ""));
+        reader.onerror = () => reject(reader.error || new Error("File read failed"));
+        reader.readAsDataURL(file);
+      });
+    }
+
+    function setBusy(active) {
+      progress.classList.toggle("active", active);
+      uploadButton.disabled = active;
+    }
+
+    function setStatus(message, error) {
+      statusEl.textContent = String(message || "STANDBY").toUpperCase();
+      statusEl.classList.toggle("error", Boolean(error));
+    }
+
+    function revealScan() {
+      scanLine.classList.remove("active");
+      void scanLine.offsetWidth;
+      scanLine.classList.add("active");
+    }
+  </script>
+</body>
+</html>

modal_app.py

@@ -16,10 +16,10 @@ import secrets as token_secrets
 import modal
 from fastapi import Header, HTTPException
 
-from snap2sim.model_io import coerce_analysis_response, parse_analysis_response, parse_html_response
-from snap2sim.prompts import build_threejs_prompt, build_vision_prompt
+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.schema import EXAMPLE_ANALYSIS, validate_analysis
-from snap2sim.three_scene import build_threejs_html
 
 
 DEFAULT_MODEL_REPO = "unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF"
@@ -81,14 +81,14 @@ 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.three_scene
+    import snap2sim.aframe_scene
 
     return {
         "ok": True,
         "modules": [
             snap2sim.model_io.__name__,
             snap2sim.schema.__name__,
-            snap2sim.three_scene.__name__,
+            snap2sim.aframe_scene.__name__,
         ],
     }
 
@@ -413,7 +413,7 @@ def runtime_probe(authorization: str = Header(default="")) -> dict[str, Any]:
             else "runtime selected"
         ),
         "verified_endpoint": "analyze_image_llamacpp",
-        "recommended_generate_endpoint": "generate_threejs",
+        "recommended_generate_endpoint": "generate_scene",
     }
 
 
@@ -447,23 +447,23 @@ 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_threejs(payload: dict[str, Any], authorization: str = Header(default="")) -> dict[str, str]:
+def generate_scene(payload: dict[str, Any], authorization: str = Header(default="")) -> dict[str, str]:
     require_authorization(authorization)
     analysis = validate_analysis(payload.get("analysis") or EXAMPLE_ANALYSIS)
-    _prompt = build_threejs_prompt(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."
         )
-    return {"html": build_threejs_html(analysis)}
+    return {"html": build_aframe_scene(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_threejs_llamacpp(payload: dict[str, Any], authorization: str = Header(default="")) -> dict[str, str]:
-    """Experimental GPU endpoint for llama.cpp Three.js code generation."""
+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."""
     require_authorization(authorization)
     analysis = validate_analysis(payload.get("analysis") or EXAMPLE_ANALYSIS)
-    response = run_llamacpp_prompt(build_threejs_prompt(analysis), max_tokens=4096)
-    return {"html": parse_html_response(response)}
+    response = run_llamacpp_prompt(build_scene_prompt(analysis), max_tokens=4096)
+    return {"html": parse_scene_response(response)}

requirements.txt

@@ -1,4 +1,4 @@
-gradio>=4.44
+gradio>=6.0.1
 huggingface_hub[hf_xet]>=0.36
 requests>=2.32
 pillow>=10.4

snap2sim/aframe_scene.py

@@ -0,0 +1,120 @@
+"""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,8 +11,8 @@ 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
-from snap2sim.three_scene import build_threejs_html
 
 
 @dataclass(frozen=True)
@@ -45,7 +45,7 @@ class InferenceClient:
 
         return validate_analysis(dict(EXAMPLE_ANALYSIS))
 
-    def generate_threejs(self, analysis: dict[str, Any]) -> str:
+    def generate_scene(self, analysis: dict[str, Any]) -> str:
         valid_analysis = validate_analysis(analysis)
         if self.settings.backend == "modal":
             response = self._post_json(self.settings.generate_url, {"analysis": valid_analysis})
@@ -54,7 +54,7 @@ class InferenceClient:
                 raise RuntimeError("Modal response did not include generated HTML.")
             return str(html)
 
-        return build_threejs_html(valid_analysis)
+        return build_aframe_scene(valid_analysis)
 
     def _post_json(self, url: str, payload: dict[str, Any]) -> dict[str, Any]:
         if not url:

snap2sim/fallback_scene.py

@@ -1,72 +0,0 @@
-"""Themed fallback visualization used when generated Three.js is unavailable."""
-
-from __future__ import annotations
-
-
-def build_fallback_html(component: str) -> str:
-    title = component.upper()
-    return f"""
-<div class="fallback-cutaway" role="img" aria-label="Fallback mechanism animation for {component}">
-  <div class="scan"></div>
-  <svg viewBox="0 0 760 430" xmlns="http://www.w3.org/2000/svg">
-    <defs>
-      <pattern id="grid" width="24" height="24" patternUnits="userSpaceOnUse">
-        <path d="M 24 0 L 0 0 0 24" fill="none" stroke="rgba(95,212,208,.14)" stroke-width="1"/>
-      </pattern>
-    </defs>
-    <rect width="760" height="430" fill="#14181F"/>
-    <rect width="760" height="430" fill="url(#grid)"/>
-    <g transform="translate(380 220)">
-      <circle r="104" fill="none" stroke="#5FD4D0" stroke-width="2" opacity=".8"/>
-      <circle class="fallback-gear" r="72" fill="none" stroke="#E8A33D" stroke-width="18"
-        stroke-dasharray="18 10"/>
-      <rect class="fallback-pawl" x="72" y="-16" width="132" height="32" rx="2"
-        fill="#E8A33D" opacity=".9"/>
-      <line x1="108" y1="-54" x2="215" y2="-112" stroke="#5FD4D0" stroke-width="1"/>
-      <text x="224" y="-116" fill="#5FD4D0" font-family="monospace" font-size="15">LOCKING PAWL</text>
-      <line x1="-54" y1="52" x2="-198" y2="122" stroke="#5FD4D0" stroke-width="1"/>
-      <text x="-342" y="132" fill="#5FD4D0" font-family="monospace" font-size="15">DRIVE GEAR</text>
-    </g>
-    <text x="32" y="44" fill="#D9D3C7" font-family="monospace" font-size="18">{title}</text>
-    <text x="32" y="394" fill="#E8A33D" font-family="monospace" font-size="13">2D FALLBACK: GENERATED 3D SCENE UNAVAILABLE</text>
-  </svg>
-</div>
-<style>
-  .fallback-cutaway {{
-    position: relative;
-    overflow: hidden;
-    border: 1px solid rgba(95, 212, 208, .28);
-    background: #14181F;
-    min-height: 430px;
-  }}
-  .fallback-cutaway svg {{
-    display: block;
-    width: 100%;
-    height: min(58vh, 560px);
-  }}
-  .fallback-gear {{
-    transform-origin: center;
-    animation: fallback-spin 3.8s linear infinite;
-  }}
-  .fallback-pawl {{
-    transform-origin: 74px 0;
-    animation: fallback-pawl 1.05s steps(2, end) infinite;
-  }}
-  .scan {{
-    position: absolute;
-    inset: 0;
-    background: linear-gradient(180deg, transparent, rgba(95, 212, 208, .16), transparent);
-    height: 26%;
-    animation: fallback-scan 2.6s ease-in-out infinite;
-    pointer-events: none;
-  }}
-  @keyframes fallback-spin {{ to {{ transform: rotate(360deg); }} }}
-  @keyframes fallback-pawl {{ 50% {{ transform: rotate(-10deg); }} }}
-  @keyframes fallback-scan {{
-    0% {{ transform: translateY(-120%); opacity: 0; }}
-    20%, 80% {{ opacity: 1; }}
-    100% {{ transform: translateY(430%); opacity: 0; }}
-  }}
-</style>
-"""
-

snap2sim/model_io.py

@@ -46,26 +46,21 @@ def coerce_analysis_response(text: str) -> dict[str, Any]:
     return validate_analysis(_generic_analysis(fallback_component))
 
 
-def parse_html_response(text: str) -> str:
-    """Extract a complete HTML document from a model response."""
+def parse_scene_response(text: str) -> str:
+    """Extract a complete A-Frame scene block from a model response."""
     raw = _strip_fences(text).strip()
-    html_start = _find_html_start(raw)
-    html_end = raw.lower().rfind("</html>")
-    if html_start < 0 or html_end < 0:
-        raise ValueError("Model response did not contain a complete HTML document.")
-    return raw[html_start : html_end + len("</html>")]
+    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()
 
 
-def _find_html_start(text: str) -> int:
-    lowered = text.lower()
-    starts = [index for index in [lowered.find("<!doctype"), lowered.find("<html")] if index >= 0]
-    return min(starts) if starts else -1
-
-
 def _json_object_candidates(text: str) -> list[tuple[int, str]]:
     candidates = []
     for index, char in enumerate(text):

snap2sim/prompts.py

@@ -18,7 +18,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 Three.js rendering.\n\n"
+        "plausible for primitive A-Frame or 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"
@@ -48,17 +48,23 @@ def build_vision_prompt() -> str:
     )
 
 
-THREEJS_SYSTEM_PROMPT = """You generate self-contained Three.js cutaway scenes.
-Return a complete HTML document with inline CSS and JavaScript only. Use
-primitive geometry, labels, OrbitControls, a play/pause control, and one
-power-on reveal animation. Do not include markdown fences."""
+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_threejs_prompt(analysis: dict[str, Any]) -> str:
+def build_scene_prompt(analysis: dict[str, Any]) -> str:
     return (
-        "Build a technical cutaway / field manual Three.js animation for this "
-        "mechanism analysis. Use a deep navy blueprint surface, warm amber "
-        "annotations, cool cyan motion paths, and monospace labels. Include "
-        "a robust fallback message inside the HTML if WebGL fails.\n\n"
+        "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)}"
     )

snap2sim/three_scene.py

@@ -1,397 +0,0 @@
-"""Deterministic Three.js scene generation from a validated mechanism payload."""
-
-from __future__ import annotations
-
-import html
-import json
-from typing import Any
-
-from snap2sim.schema import validate_analysis
-
-
-def build_threejs_html(analysis: dict[str, Any]) -> str:
-    """Return a sandboxed iframe containing a self-contained scene document."""
-    valid_analysis = validate_analysis(analysis)
-    document = _build_scene_document(valid_analysis)
-    escaped = html.escape(document, quote=True)
-    title = html.escape(str(valid_analysis.get("component", "mechanism")), quote=True)
-    return (
-        f'<iframe class="snap-scene-frame" title="Animated cutaway of {title}" '
-        'sandbox="allow-scripts allow-same-origin" '
-        f'srcdoc="{escaped}"></iframe>'
-    )
-
-
-def _build_scene_document(analysis: dict[str, Any]) -> str:
-    analysis_json = json.dumps(analysis)
-    component = html.escape(str(analysis.get("component", "mechanism")).upper())
-    return f"""<!doctype html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <style>
-    :root {{
-      --bg: #14181F;
-      --panel: #1B222B;
-      --amber: #E8A33D;
-      --cyan: #5FD4D0;
-      --text: #D9D3C7;
-      --muted: #8F968F;
-    }}
-    * {{ box-sizing: border-box; }}
-    html, body {{
-      width: 100%;
-      height: 100%;
-      margin: 0;
-      overflow: hidden;
-      color: var(--text);
-      background:
-        linear-gradient(rgba(95, 212, 208, .07) 1px, transparent 1px),
-        linear-gradient(90deg, rgba(95, 212, 208, .07) 1px, transparent 1px),
-        var(--bg);
-      background-size: 28px 28px;
-      font-family: "IBM Plex Mono", "Consolas", monospace;
-    }}
-    #scene {{
-      position: fixed;
-      inset: 0;
-    }}
-    .hud {{
-      position: fixed;
-      left: 18px;
-      right: 18px;
-      top: 16px;
-      z-index: 3;
-      display: flex;
-      align-items: flex-start;
-      justify-content: space-between;
-      gap: 16px;
-      pointer-events: none;
-    }}
-    .title {{
-      max-width: min(680px, 70vw);
-    }}
-    .title b {{
-      display: block;
-      color: var(--text);
-      font-size: 14px;
-      letter-spacing: 0;
-      text-transform: uppercase;
-    }}
-    .title span {{
-      display: block;
-      margin-top: 6px;
-      color: var(--muted);
-      font-size: 12px;
-      line-height: 1.45;
-    }}
-    #toggle {{
-      pointer-events: auto;
-      min-width: 92px;
-      border: 1px solid rgba(232, 163, 61, .8);
-      border-radius: 2px;
-      padding: 8px 12px;
-      color: #16130E;
-      background: linear-gradient(180deg, #F0B65B, #C97923);
-      font: 700 12px "IBM Plex Mono", monospace;
-      text-transform: uppercase;
-      cursor: pointer;
-    }}
-    #labels {{
-      position: fixed;
-      inset: 0;
-      z-index: 2;
-      pointer-events: none;
-    }}
-    .tag {{
-      position: absolute;
-      max-width: min(190px, 42vw);
-      transform: translate(-50%, -50%);
-      border-left: 1px solid var(--cyan);
-      padding: 4px 0 4px 8px;
-      color: var(--cyan);
-      background: rgba(20, 24, 31, .76);
-      font-size: 11px;
-      line-height: 1.25;
-      text-transform: uppercase;
-      white-space: normal;
-    }}
-    .tag::before {{
-      content: "";
-      position: absolute;
-      left: -42px;
-      top: 50%;
-      width: 40px;
-      border-top: 1px solid rgba(95, 212, 208, .7);
-    }}
-    .scan {{
-      position: fixed;
-      inset: -30% 0 auto;
-      height: 28%;
-      z-index: 4;
-      background: linear-gradient(180deg, transparent, rgba(95, 212, 208, .18), transparent);
-      animation: scan 2.2s ease-in-out 1;
-      pointer-events: none;
-    }}
-    .failure {{
-      position: fixed;
-      left: 50%;
-      top: 50%;
-      width: min(520px, calc(100vw - 40px));
-      transform: translate(-50%, -50%);
-      border: 1px solid rgba(232, 163, 61, .62);
-      padding: 18px;
-      color: var(--amber);
-      background: rgba(20, 24, 31, .92);
-      font-size: 13px;
-      line-height: 1.55;
-    }}
-    .hidden {{ display: none; }}
-    @keyframes scan {{
-      0% {{ transform: translateY(-100%); opacity: 0; }}
-      20%, 75% {{ opacity: 1; }}
-      100% {{ transform: translateY(430%); opacity: 0; }}
-    }}
-  </style>
-</head>
-<body>
-  <div id="scene"></div>
-  <div id="labels"></div>
-  <div class="scan"></div>
-  <div class="hud">
-    <div class="title">
-      <b>{component}</b>
-      <span>Primitive cutaway generated from the validated mechanism schema.</span>
-    </div>
-    <button id="toggle" type="button">Pause</button>
-  </div>
-  <div id="failure" class="failure hidden">WebGL scene failed to initialize.</div>
-  <script type="module">
-    const analysis = {analysis_json};
-    const failure = document.getElementById("failure");
-
-    function fail(error) {{
-      failure.classList.remove("hidden");
-      failure.textContent = "3D renderer unavailable: " + (error && error.message ? error.message : error);
-    }}
-
-    try {{
-      const [threeModule, controlsModule] = await Promise.all([
-        import("https://esm.sh/three@0.166.1"),
-        import("https://esm.sh/three@0.166.1/examples/jsm/controls/OrbitControls.js?deps=three@0.166.1")
-      ]);
-      initialize(threeModule, controlsModule.OrbitControls);
-    }} catch (error) {{
-      fail(error);
-    }}
-
-    function initialize(THREE, OrbitControls) {{
-      const root = document.getElementById("scene");
-      const labelsRoot = document.getElementById("labels");
-      const renderer = new THREE.WebGLRenderer({{ antialias: true, alpha: true, preserveDrawingBuffer: true }});
-      renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
-      renderer.setSize(window.innerWidth, window.innerHeight);
-      renderer.outputColorSpace = THREE.SRGBColorSpace;
-      root.appendChild(renderer.domElement);
-
-      const scene = new THREE.Scene();
-      scene.fog = new THREE.Fog(0x14181f, 9, 22);
-
-      const camera = new THREE.PerspectiveCamera(42, window.innerWidth / window.innerHeight, 0.1, 100);
-      camera.position.set(5.8, 4.6, 6.8);
-
-      const controls = new OrbitControls(camera, renderer.domElement);
-      controls.enableDamping = true;
-      controls.target.set(0, 0.15, 0);
-
-      scene.add(new THREE.HemisphereLight(0x5fd4d0, 0x14181f, 1.35));
-      const key = new THREE.DirectionalLight(0xffc36a, 2.15);
-      key.position.set(4, 7, 5);
-      scene.add(key);
-
-      const grid = new THREE.GridHelper(8, 32, 0x5fd4d0, 0x24505a);
-      grid.material.transparent = true;
-      grid.material.opacity = 0.42;
-      scene.add(grid);
-
-      const motionLineMaterial = new THREE.LineBasicMaterial({{ color: 0x5fd4d0, transparent: true, opacity: 0.56 }});
-      const parts = [];
-
-      for (const [index, part] of analysis.parts.entries()) {{
-        const mesh = buildMesh(THREE, part, index);
-        mesh.position.fromArray(part.geometry.position);
-        if (Array.isArray(part.geometry.rotation)) mesh.rotation.fromArray(part.geometry.rotation);
-        mesh.userData.basePosition = mesh.position.clone();
-        mesh.userData.baseRotation = mesh.rotation.clone();
-        mesh.userData.part = part;
-        mesh.scale.setScalar(0.001);
-        scene.add(mesh);
-        parts.push(mesh);
-
-        if (part.motion && part.motion.type !== "static") {{
-          const curve = motionCurve(THREE, part);
-          const line = new THREE.Line(
-            new THREE.BufferGeometry().setFromPoints(curve),
-            motionLineMaterial
-          );
-          scene.add(line);
-        }}
-      }}
-
-      let playing = true;
-      document.getElementById("toggle").addEventListener("click", (event) => {{
-        playing = !playing;
-        event.currentTarget.textContent = playing ? "Pause" : "Play";
-      }});
-
-      const clock = new THREE.Clock();
-      function animate() {{
-        requestAnimationFrame(animate);
-        const elapsed = clock.getElapsedTime();
-        const t = playing ? elapsed : 0;
-        for (const [index, mesh] of parts.entries()) {{
-          reveal(mesh, elapsed, index);
-          applyMotion(THREE, mesh, t);
-        }}
-        controls.update();
-        renderer.render(scene, camera);
-        updateLabels(THREE, camera, labelsRoot, parts);
-      }}
-      animate();
-
-      window.addEventListener("resize", () => {{
-        camera.aspect = window.innerWidth / window.innerHeight;
-        camera.updateProjectionMatrix();
-        renderer.setSize(window.innerWidth, window.innerHeight);
-      }});
-    }}
-
-    function buildMesh(THREE, part, index) {{
-      const g = part.geometry || {{}};
-      const size = Array.isArray(g.size) ? g.size : [1, 1, 1];
-      let geometry;
-      if (g.shape === "cylinder") {{
-        geometry = new THREE.CylinderGeometry(size[0] / 2, size[2] / 2, size[1], 48);
-      }} else if (g.shape === "sphere") {{
-        geometry = new THREE.SphereGeometry(Math.max(size[0], size[1], size[2]) / 2, 36, 18);
-      }} else if (g.shape === "rod") {{
-        geometry = new THREE.CylinderGeometry(size[0] / 2, size[0] / 2, size[2], 24);
-        geometry.rotateX(Math.PI / 2);
-      }} else if (g.shape === "gear") {{
-        geometry = gearGeometry(THREE, Math.max(size[0], size[2]) / 2, size[1], g.teeth || 18);
-      }} else {{
-        geometry = new THREE.BoxGeometry(size[0], size[1], size[2]);
-      }}
-      const color = colorFor(g.color, index);
-      const material = new THREE.MeshStandardMaterial({{
-        color,
-        metalness: 0.55,
-        roughness: 0.36,
-        emissive: color,
-        emissiveIntensity: 0.05
-      }});
-      return new THREE.Mesh(geometry, material);
-    }}
-
-    function gearGeometry(THREE, radius, depth, teeth) {{
-      const shape = new THREE.Shape();
-      const steps = teeth * 2;
-      for (let i = 0; i <= steps; i++) {{
-        const angle = (i / steps) * Math.PI * 2;
-        const r = radius * (i % 2 === 0 ? 1.0 : 0.84);
-        const x = Math.cos(angle) * r;
-        const y = Math.sin(angle) * r;
-        if (i === 0) shape.moveTo(x, y);
-        else shape.lineTo(x, y);
-      }}
-      const hole = new THREE.Path();
-      hole.absarc(0, 0, radius * 0.28, 0, Math.PI * 2, true);
-      shape.holes.push(hole);
-      const geometry = new THREE.ExtrudeGeometry(shape, {{ depth, bevelEnabled: false }});
-      geometry.center();
-      geometry.rotateX(Math.PI / 2);
-      return geometry;
-    }}
-
-    function colorFor(name, index) {{
-      const key = String(name || "").toLowerCase();
-      if (key.includes("amber") || key.includes("orange")) return 0xe8a33d;
-      if (key.includes("cyan")) return 0x5fd4d0;
-      if (key.includes("steel")) return 0x9aa4a6;
-      const palette = [0x5fd4d0, 0xe8a33d, 0xd9d3c7, 0x80b8ff, 0xf07f5a];
-      return palette[index % palette.length];
-    }}
-
-    function motionCurve(THREE, part) {{
-      const p = part.geometry.position || [0, 0, 0];
-      const points = [];
-      for (let i = 0; i < 48; i++) {{
-        const a = (i / 47) * Math.PI * 2;
-        points.push(new THREE.Vector3(p[0] + Math.cos(a) * 0.52, p[1] + 0.04, p[2] + Math.sin(a) * 0.52));
-      }}
-      return points;
-    }}
-
-    function reveal(mesh, elapsed, index) {{
-      const local = Math.max(0, Math.min(1, (elapsed - index * 0.12) / 0.75));
-      const eased = 1 - Math.pow(1 - local, 3);
-      mesh.scale.setScalar(eased);
-    }}
-
-    function applyMotion(THREE, mesh, elapsed) {{
-      const motion = mesh.userData.part.motion || {{ type: "static" }};
-      const speed = Number(motion.speed ?? 1);
-      const phase = Number(motion.phase ?? 0);
-      const axis = new THREE.Vector3(...(motion.axis || [0, 1, 0])).normalize();
-      mesh.position.copy(mesh.userData.basePosition);
-      mesh.rotation.copy(mesh.userData.baseRotation);
-      if (motion.type === "rotate") {{
-        mesh.rotateOnAxis(axis, elapsed * speed + phase);
-      }} else if (motion.type === "oscillate") {{
-        mesh.rotateOnAxis(axis, Math.sin(elapsed * speed + phase) * Number(motion.amplitude ?? 0.25));
-      }} else if (motion.type === "translate") {{
-        const range = motion.range || [-0.35, 0.35];
-        const offset = range[0] + (range[1] - range[0]) * ((Math.sin(elapsed * speed + phase) + 1) / 2);
-        mesh.position.add(axis.multiplyScalar(offset));
-      }}
-    }}
-
-    function updateLabels(THREE, camera, labelsRoot, parts) {{
-      labelsRoot.replaceChildren();
-      const width = window.innerWidth;
-      const height = window.innerHeight;
-      const entries = [];
-      for (const mesh of parts) {{
-        const pos = mesh.position.clone().project(camera);
-        if (pos.z < -1 || pos.z > 1) continue;
-        entries.push({{
-          x: clamp((pos.x * 0.5 + 0.5) * width, 76, Math.max(76, width - 76)),
-          y: clamp((-pos.y * 0.5 + 0.5) * height, 72, Math.max(72, height - 32)),
-          text: mesh.userData.part.name || mesh.userData.part.id || "part"
-        }});
-      }}
-      entries.sort((a, b) => a.y - b.y);
-      for (let i = 1; i < entries.length; i++) {{
-        entries[i].y = Math.max(entries[i].y, entries[i - 1].y + 38);
-      }}
-      const overflow = entries.length ? entries[entries.length - 1].y - (height - 32) : 0;
-      if (overflow > 0) {{
-        for (const entry of entries) entry.y -= overflow;
-      }}
-      for (const entry of entries) {{
-        const label = document.createElement("div");
-        label.className = "tag";
-        label.style.left = entry.x + "px";
-        label.style.top = entry.y + "px";
-        label.textContent = entry.text;
-        labelsRoot.appendChild(label);
-      }}
-    }}
-
-    function clamp(value, min, max) {{
-      return Math.min(max, Math.max(min, value));
-    }}
-  </script>
-</body>
-</html>"""

snap2sim/ui.py

@@ -1,225 +0,0 @@
-"""Gradio interface for Snap2Sim."""
-
-from __future__ import annotations
-
-import json
-from typing import Any
-
-import gradio as gr
-from PIL import Image
-
-from snap2sim.backend import InferenceClient, Settings
-from snap2sim.fallback_scene import build_fallback_html
-from snap2sim.schema import EXAMPLE_ANALYSIS
-
-
-CSS = """
-:root {
-  --snap-bg: #14181F;
-  --snap-panel: #1B222B;
-  --snap-line: rgba(95, 212, 208, 0.22);
-  --snap-amber: #E8A33D;
-  --snap-cyan: #5FD4D0;
-  --snap-text: #D9D3C7;
-  --snap-muted: #8F968F;
-}
-
-.gradio-container {
-  min-height: 100vh;
-  color: var(--snap-text);
-  background:
-    linear-gradient(rgba(95, 212, 208, .055) 1px, transparent 1px),
-    linear-gradient(90deg, rgba(95, 212, 208, .055) 1px, transparent 1px),
-    radial-gradient(circle at 85% 15%, rgba(232, 163, 61, .12), transparent 30%),
-    var(--snap-bg) !important;
-  background-size: 28px 28px, 28px 28px, auto, auto !important;
-  font-family: 'IBM Plex Mono', monospace !important;
-}
-
-.snap-shell {
-  max-width: 1540px;
-  margin: 0 auto;
-}
-
-.snap-title h1 {
-  margin: 0 0 4px;
-  color: var(--snap-text);
-  font-family: 'Archivo Narrow', sans-serif;
-  font-size: clamp(38px, 5vw, 76px);
-  line-height: .9;
-  letter-spacing: 0;
-  text-transform: uppercase;
-}
-
-.snap-title p {
-  max-width: 860px;
-  color: var(--snap-muted);
-  font-size: 14px;
-  line-height: 1.6;
-}
-
-.snap-frame {
-  border: 1px solid var(--snap-line);
-  background: rgba(20, 24, 31, .8);
-  box-shadow: inset 0 0 0 1px rgba(232, 163, 61, .06);
-}
-
-.snap-frame label,
-.snap-frame .label-wrap span {
-  color: var(--snap-cyan) !important;
-  font-family: 'IBM Plex Mono', monospace !important;
-  text-transform: uppercase;
-}
-
-.snap-frame textarea,
-.snap-frame input {
-  background: #10141A !important;
-  color: var(--snap-text) !important;
-  border-color: var(--snap-line) !important;
-  font-family: 'IBM Plex Mono', monospace !important;
-}
-
-.snap-run {
-  border: 1px solid rgba(232, 163, 61, .7) !important;
-  background: linear-gradient(180deg, #F0B65B, #C97923) !important;
-  color: #16130E !important;
-  font-family: 'Archivo Narrow', sans-serif !important;
-  font-size: 18px !important;
-  font-weight: 700 !important;
-  text-transform: uppercase;
-  border-radius: 2px !important;
-}
-
-.snap-run:hover {
-  filter: brightness(1.08);
-}
-
-.snap-status {
-  min-height: 42px;
-  color: var(--snap-amber);
-  font-size: 13px;
-  text-transform: uppercase;
-}
-
-.snap-html iframe,
-.snap-html > div {
-  min-height: 560px;
-}
-
-.snap-scene-frame {
-  display: block;
-  width: 100%;
-  min-height: 560px;
-  border: 0;
-  background: #14181F;
-}
-
-.snap-json pre {
-  color: var(--snap-text) !important;
-  background: #10141A !important;
-}
-
-.snap-explain {
-  color: var(--snap-text);
-  line-height: 1.65;
-}
-"""
-
-
-def format_explanation(analysis: dict[str, Any]) -> str:
-    parts = analysis.get("parts", [])
-    part_lines = "\n".join(
-        f"- **{part.get('name', 'part')}**: {part.get('role', 'role unknown')}"
-        for part in parts
-    )
-    sequence = "\n".join(f"{index + 1}. {step}" for index, step in enumerate(analysis.get("motion_sequence", [])))
-    return (
-        f"### {analysis.get('component', 'Component')}\n\n"
-        f"{analysis.get('summary', '')}\n\n"
-        f"**Trigger:** {analysis.get('trigger', 'unknown')}\n\n"
-        f"**Motion sequence**\n{sequence}\n\n"
-        f"**Parts**\n{part_lines}"
-    )
-
-
-def initial_status() -> str:
-    settings = Settings()
-    if settings.backend == "modal":
-        configured = bool(settings.analyze_url and settings.generate_url)
-        return "STANDBY: MODAL BACKEND CONFIGURED" if configured else "STANDBY: MODAL BACKEND MISSING URLS"
-    return "STANDBY: LOCAL PLACEHOLDER BACKEND"
-
-
-def run_pipeline(image: Image.Image | None) -> tuple[str, str, str, str]:
-    client = InferenceClient(Settings())
-    try:
-        analysis = client.analyze_image(image)
-        html = client.generate_threejs(analysis)
-        status = "CUTAWAY READY"
-    except Exception as exc:
-        analysis = dict(EXAMPLE_ANALYSIS)
-        html = build_fallback_html(str(analysis.get("component", "mechanism")))
-        status = f"FALLBACK RENDER ACTIVE: {exc}"
-
-    return (
-        html,
-        format_explanation(analysis),
-        json.dumps(analysis, indent=2),
-        status,
-    )
-
-
-def build_app() -> gr.Blocks:
-    with gr.Blocks(css=CSS, title="Inside the Machine") as demo:
-        with gr.Column(elem_classes=["snap-shell"]):
-            gr.HTML(
-                """
-                <link rel="preconnect" href="https://fonts.googleapis.com">
-                <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-                <link href="https://fonts.googleapis.com/css2?family=Archivo+Narrow:wght@500;700&family=IBM+Plex+Mono:wght@400;500;700&display=swap" rel="stylesheet">
-                <section class="snap-title">
-                  <h1>Inside the Machine</h1>
-                  <p>Upload a component photo. Snap2Sim drafts a mechanical teardown,
-                  then renders an annotated cutaway animation for repair cafes,
-                  shop classrooms, and curious builders.</p>
-                </section>
-                """
-            )
-
-            with gr.Row(equal_height=False):
-                with gr.Column(scale=5, elem_classes=["snap-frame"]):
-                    scene = gr.HTML(
-                        build_fallback_html("waiting for upload"),
-                        label="Cutaway viewport",
-                        elem_classes=["snap-html"],
-                    )
-                with gr.Column(scale=3, elem_classes=["snap-frame"]):
-                    image = gr.Image(type="pil", label="Component photo")
-                    run = gr.Button("Analyze Assembly", elem_classes=["snap-run"])
-                    status = gr.Textbox(
-                        value=initial_status(),
-                        label="Workshop status",
-                        interactive=False,
-                        elem_classes=["snap-status"],
-                    )
-                    explanation = gr.Markdown(
-                        "Upload a photo and run the analyzer.",
-                        elem_classes=["snap-explain"],
-                    )
-
-            with gr.Accordion("Structured mechanism JSON", open=False):
-                raw_json = gr.Code(
-                    value="{}",
-                    language="json",
-                    label="Vision-to-scene contract",
-                    elem_classes=["snap-json"],
-                )
-
-            run.click(
-                fn=run_pipeline,
-                inputs=[image],
-                outputs=[scene, explanation, raw_json, status],
-                show_progress="full",
-            )
-
-    return demo