Reduce motion axis bias

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

AGENTS.md

@@ -42,6 +42,7 @@ technical cutaway animation.
 ## Project Structure
 
 - `PROMPT.md` - original product, model, design, and delivery requirements.
+- `docs/` - implementation notes, review passes, and representative fixtures.
 - `README.md` - quickstart, runtime decision, and repo map.
 - `SECURITY.md` - public/private data handling rules for humans and agents.
 - `.env.example` - public Hugging Face Space / local demo variables.
@@ -189,7 +190,8 @@ technical cutaway animation.
   on June 14, 2026: `/analyze_image` returned a validated mechanism payload
   through the secured Modal bearer-token flow, and `/generate_scene` returned
   an A-Frame `<a-scene>` block.
-- Implemented the `REVIEW.md` security pass on June 14, 2026:
+- Implemented the `docs/reviews/security-hardening.md` security pass on June
+  14, 2026:
   Space-layer rate limiting for `/analyze_image` and `/generate_scene`,
   upload-size caps, PIL decompression-bomb handling, clean image decode errors,
   unique Modal temp image files with cleanup, and no model-authored scene HTML.
@@ -209,7 +211,8 @@ technical cutaway animation.
   `/analyze_image` returned a validated mechanism payload through the secured
   Modal bearer-token flow, and `/generate_scene` returned
   `{ "renderer": "three", "analysis": ... }` with no HTML field.
-- Implemented the `REVIEW2.md` local code pass on June 14, 2026: fixed the
+- Implemented the `docs/reviews/interaction-and-fallback-review.md` local code
+  pass on June 14, 2026: fixed the
   label-overlay pointer-events bug that blocked OrbitControls, added bounded
   camera controls plus Reset view and orbit/zoom hint, changed the source-photo
   preview to a stable contained image box, added optional normalized per-part
@@ -220,7 +223,8 @@ technical cutaway animation.
   the last complete JSON object, and llama.cpp analysis now uses larger
   token/context/timeout budgets (`4096` output tokens, `8192` context, `300s`
   timeout at the analysis call site).
-- Local verification after the `REVIEW2.md` pass: schema/parser checks passed,
+- Local verification after the `docs/reviews/interaction-and-fallback-review.md`
+  pass: schema/parser checks passed,
   FastAPI `TestClient` confirmed `/`, `/analyze_image`, and `/generate_scene`,
   and browser verification confirmed left-drag orbit, right-drag pan, wheel
   zoom, mobile canvas event targeting, contained source preview, annotated-photo
@@ -235,7 +239,8 @@ technical cutaway animation.
   `run_analysis_raw_check` parsed strict JSON successfully in `35.12s`, and
   `run_analysis_endpoint_check` returned a parsed per-image `targeting reticle`
   payload at `0.7` confidence.
-- User decision after the `REVIEW2.md` pass: use the real Modal
+- User decision after the `docs/reviews/interaction-and-fallback-review.md`
+  pass: use the real Modal
   `analyze_image_llamacpp` analysis path for the demo. `INFERENCE_BACKEND` now
   defaults to `modal`; `INFERENCE_BACKEND=local` is an explicit UI-development
   sample mode only and should not be used for public submission.
@@ -261,7 +266,8 @@ technical cutaway animation.
   reveal. Local browser verification confirmed the scene still renders, orbit
   drag still works, the canvas remains the pointer target, the source preview
   remains contained, and the mobile layout has no horizontal overflow.
-- Implemented the `FEATURE.md` confidence-threshold control on June 14, 2026:
+- Implemented the `docs/features/confidence-threshold.md`
+  confidence-threshold control on June 14, 2026:
   added a toolbar slider defaulting to `0.5`, made the browser recompute render
   mode from cached analysis plus the current slider value, and kept slider
   changes local with no extra `/analyze_image` or `/generate_scene` calls.
@@ -278,46 +284,54 @@ technical cutaway animation.
   returned real Modal analysis for `Target Reticle` at `0.7` confidence with 3
   parts, and `/generate_scene` returned `renderer: three`, `render_mode: three`,
   and no HTML field.
-- Implemented the `FEATURE.md` confidence-threshold re-spec on June 14, 2026:
+- Implemented the `docs/features/confidence-threshold.md`
+  confidence-threshold re-spec on June 14, 2026:
   the slider is enabled before the first upload, sends `confidence_threshold`
   only with `/generate_scene`, no longer re-renders cached analysis on slider
   movement, and the server clamps/coerces the threshold before selecting
   `render_mode`. The browser now trusts the server's `render_mode` and only
   downgrades when geometry or annotation data is missing.
-- Implemented the `FEATURE2.md` annotated-photo fallback pass: fixed portrait
+- Implemented the `docs/features/annotated-photo-fallback.md` fallback pass:
+  fixed portrait
   and landscape image containment by giving the annotation frame a definite
   viewport-bounded box, added numbered marker dots, leader lines, and optional
   annotation bounding boxes, and kept all annotation text rendered through
   `textContent`.
-- Implemented the `FEATURE3.md` renderer/prompt vocabulary pass: added
+- Implemented the `docs/features/renderer-vocabulary.md` renderer/prompt
+  vocabulary pass: added
   deterministic `cone`, `capsule`, `torus`, and `spring` shapes; added `screw`,
   `orbit`, and `pulse` motions; raised the usable part cap to 6 across prompt,
   schema, coercion, and browser renderability; and updated the sample analysis
   to exercise all four new primitives.
-- Local verification after the `FEATURE2.md` / `FEATURE3.md` pass: schema and
-  coercion checks passed, FastAPI `TestClient` confirmed `/`, `/analyze_image`,
-  and `/generate_scene`, browser verification confirmed contained portrait and
+- Local verification after the `docs/features/annotated-photo-fallback.md` /
+  `docs/features/renderer-vocabulary.md` pass: schema and coercion checks
+  passed, FastAPI `TestClient` confirmed `/`, `/analyze_image`, and
+  `/generate_scene`, browser verification confirmed contained portrait and
   landscape annotated-photo fallbacks with labels in bounds and no mobile
-  horizontal overflow, and the deterministic Three.js path reached
-  `CUTAWAY READY` with a nonblank six-part scene.
+  horizontal overflow, and the deterministic Three.js path reached `CUTAWAY
+  READY` with a nonblank six-part scene.
 - Committed and pushed `682623a` (`Expand renderer vocabulary and annotation
   fallback`) to GitHub `main`. GitHub Actions sync run `27518719440` completed
   successfully, and the private Hugging Face Space reported SHA
   `682623a979e351c3fb6d5b5b9ade907c7a979aea`.
-- Deployed the updated Modal app after the `FEATURE2.md` / `FEATURE3.md` pass
-  so `analyze_image_llamacpp` uses the richer prompt plus expanded schema and
-  coercion. Authenticated private Space verification passed: root returned
-  `200` with the updated vocabulary shell, a synthetic target image returned a
-  real Modal analysis for `piston mechanism` at `0.85` confidence with 3 parts,
-  `/generate_scene` returned `renderer: three`, `render_mode: three`, and no
-  HTML field, and a high confidence threshold returned `render_mode: annotate`.
-- Implemented the `FEATURE4.md` prompt-role split on June 15, 2026: moved the
+- Deployed the updated Modal app after the
+  `docs/features/annotated-photo-fallback.md` /
+  `docs/features/renderer-vocabulary.md` pass so `analyze_image_llamacpp` uses
+  the richer prompt plus expanded schema and coercion. Authenticated private
+  Space verification passed: root returned `200` with the updated vocabulary
+  shell, a synthetic target image returned a real Modal analysis for `piston
+  mechanism` at `0.85` confidence with 3 parts, `/generate_scene` returned
+  `renderer: three`, `render_mode: three`, and no HTML field, and a high
+  confidence threshold returned `render_mode: annotate`.
+- Implemented the `docs/features/vision-prompt-roles.md` prompt-role split on
+  June 15, 2026: moved the
   invariant analysis contract into `VISION_SYSTEM_PROMPT`, reduced
   `build_vision_prompt()` to a backward-compatible per-image user-prompt alias,
   added `build_vision_messages()`, and wired Modal llama.cpp analysis calls to
   pass `-sys` with a fallback that prepends the system text only if the deployed
   binary rejects the system-prompt flag.
-- Verification after the `FEATURE4.md` pass: prompt-helper checks,
+- Verification after the `docs/features/vision-prompt-roles.md` pass:
+  prompt-helper checks,
   schema/parser/coercion checks, FastAPI `TestClient` checks for `/`,
   `/analyze_image`, and `/generate_scene`, and a `modal_app.py` import/helper
   check all passed locally. Modal dev raw analysis parsed strict JSON in
@@ -334,7 +348,8 @@ technical cutaway animation.
   returned a real Modal analysis for `cutaway mechanism` at `0.7` confidence
   with 3 parts, and `/generate_scene` returned `renderer: three`,
   `render_mode: three`, and no HTML field.
-- Implemented the `REVIEW3.md` deterministic renderer pass on June 15, 2026:
+- Implemented the `docs/reviews/scene-geometry-review.md` deterministic
+  renderer pass on June 15, 2026:
   axial and disk-like primitives now infer their axis from `geometry.size`,
   radius comes from the cross-section pair, explicit `geometry.rotation`
   remains additive, the Three.js assembly recenters before reveal animation,
@@ -342,11 +357,35 @@ technical cutaway animation.
   aspect, the grid moves to the recentered assembly bottom, and label
   projection uses world positions. Prompt wording now tells the model that the
   renderer infers primitive orientation from the odd-one-out size dimension.
-- Local verification after the `REVIEW3.md` pass: prompt/schema imports,
+- Local verification after the `docs/reviews/scene-geometry-review.md` pass:
+  prompt/schema imports,
   schema validation, parser/coercion validation, FastAPI `TestClient` checks
-  in `INFERENCE_BACKEND=local`, browser verification for `MODEL_OUTPUT.json`
-  and `EXAMPLE_ANALYSIS`, desktop/mobile nonblank screenshots, mobile
+  in `INFERENCE_BACKEND=local`, browser verification for
+  `docs/fixtures/mini-fan-analysis.json` and `EXAMPLE_ANALYSIS`,
+  desktop/mobile nonblank screenshots, mobile
   no-overflow measurement, orbit drag, and Reset view all passed.
+- Reworked `README.md` for Build Small judging on June 15, 2026: added
+  judge-facing YAML tags for the Backyard AI track plus Llama Champion,
+  NVIDIA Nemotron Quest, Modal Award, OpenAI Codex, Off-Brand, Best Demo, and
+  Sharing is Caring; shifted the body from a maintainer runbook to a public
+  pitch with concise idea, demo, tech stack, verification, and setup sections;
+  kept private Modal endpoint URLs and credentials out of public docs.
+- Cleaned up repository notes on June 15, 2026: moved feature specs to
+  `docs/features/`, review passes to `docs/reviews/`, and the mini-fan model
+  output fixture to `docs/fixtures/mini-fan-analysis.json`; added
+  `docs/README.md` as an index.
+- Implemented the `docs/reviews/motion-axis-bias.md` pass on June 15, 2026:
+  de-anchored the vision prompt from `[0, 1, 0]`, added balanced X/Y/Z axis
+  examples and a shaft exemplar, made missing browser-side motion axes derive
+  from the same size-based primitive axis used for geometry orientation, and
+  removed the hard-coded Y axis from the generic fallback rotor.
+- Verification after the motion-axis pass: schema/parser/coercion checks
+  passed, FastAPI `TestClient` checks passed in `INFERENCE_BACKEND=local`,
+  Playwright renderer probes confirmed missing-axis X, Y, and Z parts infer
+  the expected axes with no horizontal overflow, Modal dev
+  `run_analysis_endpoint_check` returned a rotating `dial` with
+  `axis: [1, 0, 0]`, stable Modal deploy completed, and unauthenticated stable
+  `runtime_probe` still returned `401 Unauthorized`.
 
 ## Next Work
 
@@ -357,6 +396,5 @@ technical cutaway animation.
 - Keep the Hugging Face Space private until the user explicitly approves making
   it public for submission.
 - 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`.
+  flea market. What is it? How does it work inside?" Maintain the judge-facing
+  YAML tags and public pitch if future README updates are needed.

README.md

@@ -5,208 +5,160 @@ app_file: app.py
 license: mit
 colorFrom: blue
 colorTo: yellow
+short_description: Photograph a mystery part and get an animated mechanical cutaway.
+models:
+- unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF
+tags:
+- build-small-hackathon
+- backyard-ai
+- llama-champion
+- nvidia-nemotron-quest
+- modal-award
+- openai-codex
+- off-brand
+- best-demo
+- sharing-is-caring
+- llama-cpp
+- gguf
+- gradio
+- three-js
 ---
 
-# Snap2Sim
+# Snap2Sim: Inside the Machine
 
 You find a small metal cylinder at a flea market. What is it? How does it work
 inside?
 
-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.
+Snap2Sim turns a photo of a hardware component into a narrated mechanical
+cutaway. Drop in a picture of a valve, lock, pump, gear train, fan, latch, or
+other mystery part; the app identifies the likely mechanism, names the internal
+pieces, and renders a moving 3D field-manual view that explains how the object
+works.
 
-The local app serves a trusted `index.html` shell through `gradio.Server` and
-exposes `/analyze_image` plus a compatibility `/generate_scene` route. The demo
-path uses the real Modal llama.cpp analysis endpoint by default; the fixed local
-sample backend is available only when `INFERENCE_BACKEND=local` is explicitly
-set for development.
+The goal is not just recognition. It is the moment a curious maker gets to see
+the hidden motion: the plunger sliding, the spring loading, the rotor spinning,
+the pawl catching, the port opening.
 
-## Run Locally
+## Demo
 
-```powershell
-pip install -r requirements.txt
-python app.py
-```
+- Hugging Face Space: https://huggingface.co/spaces/jasondo111/Snap2Sim
+- App host: https://jasondo111-snap2sim.hf.space
+- Source of truth: https://github.com/Bigstonks1/Snap2Sim
 
-Set `INFERENCE_BACKEND=modal`, `MODAL_ANALYZE_URL`, and `SNAP2SIM_API_TOKEN`
-to point the Gradio app at the deployed Modal `analyze_image_llamacpp`
-endpoint. `/generate_scene` is deterministic in the Space process and returns a
-validated scene descriptor.
+The Space is private until final submission approval. The app is built as a
+Gradio Space with a custom `gradio.Server` shell and can be made public from the
+same repository when ready.
 
-For quick UI-only development without Modal, explicitly set
-`INFERENCE_BACKEND=local`. That mode returns a sample mechanism and should not
-be used for the public demo.
+## Hackathon Fit
 
-For the deployed demo configuration, copy `.env.example` into local environment
-variables or Hugging Face Space variables. Do not put tokens in `.env.example`;
-see `SECURITY.md`.
+Snap2Sim is a Backyard AI project for people who learn by taking things apart:
+garage tinkerers, repair hobbyists, thrift-store scavengers, robotics students,
+and anyone holding an unknown part and wondering what is going on inside.
 
-## Runtime Preflight
+The README metadata tags request consideration for:
+
+| Track or badge | Why it applies |
+|---|---|
+| Backyard AI | Explains real-world objects from a user's own photo. |
+| Llama Champion | Runs the primary model through llama.cpp with GGUF assets. |
+| NVIDIA Nemotron Quest | Uses NVIDIA Nemotron 3 Nano Omni as the vision-reasoning model. |
+| Modal Award | GPU inference is deployed through Modal with cached model assets. |
+| OpenAI Codex | Built with Codex assistance and Codex-attributed commits in the linked GitHub repo. |
+| Off-Brand | The experience is a branded maker tool, not a generic chatbot or image demo. |
+| Best Demo / Sharing is Caring | Targeted once the public demo video and social post links are added to this README. |
+| Off the Grid | Not claimed while inference runs on Modal. |
+
+## How It Works
+
+1. The browser accepts a component photo and sends it to the Space's same-origin
+   `/analyze_image` API.
+2. The Space calls a secured Modal endpoint running
+   `unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF` through
+   llama.cpp and `llama-mtmd-cli`.
+3. Nemotron returns a structured mechanism JSON payload: component name,
+   confidence, internal parts, geometry hints, motion types, annotations, and a
+   plain-language explanation.
+4. `/generate_scene` validates the analysis and chooses the render mode.
+5. The browser renders the result with trusted deterministic Three.js code. If a
+   confident 3D reconstruction is not justified, it falls back to annotated
+   callouts on the original photo instead of pretending.
+
+The model describes the mechanism. The browser owns the rendering. That keeps
+the demo reliable and avoids injecting model-authored HTML or JavaScript into
+the page.
+
+## Tech Stack
+
+- Frontend: plain `index.html`, CSS, and JavaScript served directly by
+  `gradio.Server`.
+- Rendering: deterministic Three.js primitives, labels, OrbitControls, camera
+  fitting, and an annotated-photo fallback.
+- Model runtime: NVIDIA Nemotron 3 Nano Omni 30B-A3B GGUF, `UD-Q4_K_M`, with
+  `mmproj-F16.gguf` through llama.cpp.
+- GPU service: Modal, with weights cached in a Modal Volume and bearer-token
+  protection between the Space and Modal.
+- Space runtime: Hugging Face `cpu-basic`; expensive inference happens on Modal.
+- Contract: JSON schema validation in `snap2sim/schema.py` before anything is
+  rendered.
+
+The primary model is approximately 30B total parameters with roughly 3B active
+per MoE token, keeping the single-model pipeline under the hackathon's 32B model
+budget.
+
+## What Makes It Different
+
+Most image demos stop at a label. Snap2Sim tries to answer the maker's next
+question: "what would I see if I cut this open?"
+
+- It produces a mechanism explanation, not just a class name.
+- It maps internal parts into a moving technical cutaway.
+- It shows uncertainty honestly with a confidence threshold and a photo
+  annotation fallback.
+- It uses a custom public-facing interface instead of a default chat or form UI.
+- It keeps secrets and GPU endpoints server-side while the client calls only
+  same-origin APIs.
+
+## Current Verification
+
+Recent local and deployed checks confirmed:
+
+- The private Space serves the trusted `index.html` shell.
+- `/analyze_image` returns validated mechanism payloads through the secured
+  Modal bearer-token flow.
+- `/generate_scene` returns a deterministic Three.js scene descriptor, not raw
+  HTML.
+- The renderer handles six-part scenes, axial orientation from geometry sizes,
+  geometry-aware motion-axis fallback, fitted camera framing, orbit controls,
+  reset view, mobile layout, and annotated-photo fallbacks.
+- Unauthenticated Modal requests return `401 Unauthorized`.
 
-Run the metadata preflight before spending GPU time:
+## Run Locally
 
 ```powershell
-python scripts/verify_runtime_assets.py
+pip install -r requirements.txt
+python app.py
 ```
 
-This confirms the selected GGUF quant and `mmproj` projector are present in the
-Hugging Face repo without downloading the model. It does not prove image input
-works in llama.cpp.
-
-## Runtime Decision
-
-Verification on June 13, 2026 found:
-
-- `unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF` includes GGUF
-  quant files, `mmproj-BF16.gguf`, `mmproj-F16.gguf`, and `mmproj-F32.gguf`.
-- The same model card includes llama.cpp launch instructions.
-- llama.cpp source includes the `nemotron_h_moe` text architecture.
-- llama.cpp public docs list multimodal server support, but the visible
-  supported-model list does not explicitly name Nemotron Omni or CRADIO v4-H.
-
-So the preferred path is single-model GGUF via llama.cpp. The Modal GPU smoke
-test passed on June 13, 2026 with `UD_Q4_K_M` and `mmproj-F16.gguf`, confirming
-that `llama-mtmd-cli` accepts image input for this pairing.
-
-If endpoint quality is not strong enough for the demo, use
-`nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-NVFP4` through vLLM or
-Transformers/custom code for vision analysis, and keep the GGUF path for
-text-only Three.js generation.
+For UI-only development, set:
 
-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
+```powershell
+$env:INFERENCE_BACKEND="local"
+python app.py
+```
 
-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.
+For the real demo path, configure the public variables and private token as
+described in `.env.example` and `SECURITY.md`. Do not commit tokens, Modal
+endpoint URLs, uploaded user photos, or downloaded model weights.
 
-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.
+## Runtime Preflight
 
-| 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 using `gradio.Server`; serves
-  `index.html` at `/` and exposes `/analyze_image` plus `/generate_scene`.
-- `index.html` - plain HTML/CSS/JS shell with upload orchestration,
-  source-photo preview, and deterministic browser-side Three.js rendering.
-- `modal_app.py` - Modal web endpoint scaffold.
-- `scripts/verify_runtime_assets.py` - GGUF/mmproj metadata preflight.
-- `snap2sim/backend.py` - backend selection and HTTP client.
-- `snap2sim/prompts.py` - prompt template for vision analysis.
-- `snap2sim/schema.py` - JSON schema and sample analysis payload.
-
-## Current Rendering Architecture
-
-The app uses `gradio.Server` to serve `index.html` directly. This avoids
-Gradio component script stripping and lets the page load the trusted Three.js
-renderer normally.
-
-Runtime flow:
-
-1. Browser encodes the uploaded photo and posts it to `/analyze_image`.
-2. Backend returns the validated mechanism JSON.
-3. Browser posts the analysis plus the current confidence threshold to
-   `/generate_scene` for a validated scene descriptor.
-4. Browser renders deterministic Three.js primitives when geometry is usable,
-   or overlays text-only callouts on the uploaded photo when the model only has
-   image-space annotations.
-5. A browser-side confidence slider controls the minimum analysis confidence
-   needed for the 3D cutaway. Moving it only updates the next-run value; it does
-   not re-render cached analysis or call the model.
-6. `/generate_scene` returns a validated
-   `{ "renderer": "...", "render_mode": "...", "analysis": ... }` descriptor
-   instead of model-authored HTML. The returned `render_mode` is the source of
-   truth for the visible renderer, with the browser only downgrading when
-   required data is missing.
-
-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, source-photo preview, and a
-play/pause control. The confidence slider defaults to 50%, matching the
-server's fallback threshold, and the generation route is authoritative for the
-visible render mode.
-
-The deterministic renderer supports `box`, `cylinder`, `sphere`, `gear`, `rod`,
-`cone`, `capsule`, `torus`, and `spring` primitives, plus `static`, `rotate`,
-`oscillate`, `translate`, `screw`, `orbit`, and `pulse` motions. The
-annotated-photo fallback keeps the uploaded image contained in the viewport and
-draws marker dots, leader lines, and optional normalized bounding boxes from
-validated annotation data.
-
-The browser no longer injects model-authored HTML into the DOM. The model's
-job is limited to the structured analysis JSON contract in `snap2sim/schema.py`.
-
-## Modal Deployment Path
-
-Deploy the Modal app before wiring a public demo so the llama.cpp endpoint uses
-the current prompt, parsing, and coercion code:
+Check the selected GGUF and projector metadata before spending GPU time:
 
 ```powershell
-python -m modal deploy modal_app.py
+python scripts/verify_runtime_assets.py
 ```
 
-If Modal is not authenticated on the machine, run `python -m modal token new`
-first.
-
-Current production deployment:
-
-- Deployment: https://modal.com/apps/bigstonks1/main/deployed/snap2sim-inside-the-machine
-- Web endpoint URLs are configured in Hugging Face Space variables and protected
-  by the `SNAP2SIM_API_TOKEN` bearer-token secret.
-
-Useful deployment functions/endpoints:
-
-- `check_remote_imports` verifies Modal can import the local `snap2sim` package
-  before running expensive GPU/model work.
-- `download_runtime_assets` caches the selected GGUF quant and `mmproj` file in
-  the `snap2sim-hf-cache` Modal Volume.
-- `smoke_test_llamacpp_image` builds llama.cpp with CUDA and runs one image
-  prompt through `llama-mtmd-cli` using the cached GGUF and `mmproj`.
-- `run_analysis_endpoint_check` calls the real llama.cpp analysis task with a
-  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 active on the compatibility endpoint.
-- `analyze_image` preserves the HTTP contract for old wiring, but the demo
-  should use `analyze_image_llamacpp`.
-- `generate_scene` and `generate_scene_llamacpp` are compatibility endpoints
-  that return the deterministic Three.js scene descriptor.
-- `analyze_image_llamacpp` is the experimental GPU endpoint for the llama.cpp
-  runtime path after the smoke test passes.
-
-Runtime environment knobs:
-
-- `SNAP2SIM_MODEL_REPO`, default
-  `unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF`
-- `SNAP2SIM_GGUF_QUANT`, default `UD-Q4_K_M`
-- `SNAP2SIM_MMPROJ_FILE`, default `mmproj-F16.gguf`
-- `SNAP2SIM_RUNTIME_MODE`, default `placeholder`
-- `SNAP2SIM_SMOKE_GPU`, default `L40S`
-- `SNAP2SIM_RUNTIME_GPU`, default `L40S`
-
-For the public demo, point `MODAL_ANALYZE_URL` at the validated
-`analyze_image_llamacpp` endpoint. `SNAP2SIM_RUNTIME_MODE=placeholder` can stay
-set because only the legacy `analyze_image` compatibility endpoint reads it.
-The browser renders scenes deterministically from the validated analysis JSON.
-
-Run the deployment preflight in this order:
+Useful Modal checks:
 
 ```powershell
 python -m modal run modal_app.py::check_remote_imports
@@ -215,74 +167,23 @@ python -m modal run modal_app.py::smoke_test_llamacpp_image
 python -m modal run modal_app.py::run_analysis_endpoint_check
 ```
 
-Or run both steps together:
+On Windows, use UTF-8 output when running Modal commands:
 
 ```powershell
-python -m modal run modal_app.py::run_runtime_preflight
-```
-
-The smoke test returns a JSON object. Treat `"ok": true` as evidence that
-llama.cpp accepted image input with the selected GGUF and `mmproj`. The analysis
-endpoint has a bounded generation path and a local coercion fallback because the
-reasoning model can emit verbose `<think>` text before JSON.
-
-## Hugging Face Space Configuration
-
-Current Space:
-
-- Hub repo: https://huggingface.co/spaces/jasondo111/Snap2Sim
-- App host: https://jasondo111-snap2sim.hf.space
-- Visibility: private as of the latest deployment
-- Runtime: `RUNNING` on `cpu-basic`
-
-The Space is configured as a Gradio SDK app with these variables:
-
-```text
-INFERENCE_BACKEND=modal
-MODAL_ANALYZE_URL=<stored in Hugging Face Space variables>
-MODAL_GENERATE_URL=<optional compatibility value>
-INFERENCE_TIMEOUT_SECONDS=300
+$env:PYTHONIOENCODING="utf-8"; python -m modal run modal_app.py::run_runtime_preflight
 ```
 
-The Space also needs `SNAP2SIM_API_TOKEN` as a Hugging Face Space secret. The
-same value must be present in the Modal `snap2sim-api-auth` secret. Do not put
-that token in `.env.example`, README, logs, or prompts.
-
-Before making the Space public, keep the Space-layer protections active:
-`app.py` rate-limits `/analyze_image` and `/generate_scene`, rejects oversized
-base64/image payloads, and treats decompression-bomb images as request errors.
-
-From this repo, deploy after authenticating with Hugging Face:
-
-```powershell
-hf auth login --force
-hf repos create jasondo111/Snap2Sim --type space --space-sdk gradio --exist-ok --env-file .env.example
-hf upload jasondo111/Snap2Sim . . --repo-type space --commit-message "Deploy Snap2Sim demo"
-```
-
-The `.hfignore` file excludes local credentials, caches, downloaded model
-weights, and Playwright artifacts from uploads.
-
-For an authenticated API check against this private Space, use `handle_file`
-with `gradio_client`; plain string file paths are rejected by the Gradio 6 image
-input schema.
-
-## GitHub to Hugging Face Sync
-
-GitHub is the source of truth for this project:
-
-- GitHub repo: https://github.com/Bigstonks1/Snap2Sim
-- Hugging Face Space: configured separately as the sync target
-
-The workflow at `.github/workflows/sync_to_hf.yml` syncs pushes to the `main`
-branch into `jasondo111/Snap2Sim`. It requires a GitHub Actions secret named
-`HF_TOKEN` with write access to that Space.
-
-Do not edit files directly in the Hugging Face Space. Those changes are not the
-source of truth and will be overwritten by the next GitHub-to-Hugging Face sync.
-Configure runtime values such as `MODAL_ANALYZE_URL`, `MODAL_GENERATE_URL`, and
-`SNAP2SIM_API_TOKEN` through Hugging Face Space variables/secrets instead of
-committing them.
+## Repository Map
+
+- `app.py` - Gradio Server app, same-origin APIs, image validation, rate limits.
+- `index.html` - upload flow, analysis panel, Three.js renderer, fallback UI.
+- `modal_app.py` - Modal deployment, llama.cpp runtime, diagnostics.
+- `docs/` - implementation notes, review passes, and representative fixtures.
+- `snap2sim/backend.py` - backend selection and authenticated Modal client.
+- `snap2sim/prompts.py` - vision prompt contract.
+- `snap2sim/schema.py` - mechanism JSON schema and sample payload.
+- `scripts/verify_runtime_assets.py` - Hugging Face model metadata preflight.
+- `SECURITY.md` - public/private handling rules for deployment.
 
 ## Acknowledgements
 

docs/README.md

@@ -0,0 +1,30 @@
+# Project Notes
+
+This folder keeps implementation notes, review passes, and fixtures out of the
+repository root while preserving the context that led to the current demo.
+
+## Features
+
+- `features/confidence-threshold.md` - confidence threshold control and
+  server-side render-mode selection.
+- `features/annotated-photo-fallback.md` - contained photo fallback with
+  markers, leader lines, and annotation boxes.
+- `features/renderer-vocabulary.md` - expanded deterministic primitive and
+  motion vocabulary.
+- `features/vision-prompt-roles.md` - split system/user prompt contract for
+  llama.cpp analysis.
+
+## Reviews
+
+- `reviews/security-hardening.md` - Space and Modal security pass.
+- `reviews/interaction-and-fallback-review.md` - camera controls, source-photo
+  preview, and fallback strategy.
+- `reviews/scene-geometry-review.md` - primitive orientation, sizing, camera
+  fitting, and Y alignment.
+- `reviews/motion-axis-bias.md` - prompt and renderer defaults for reducing
+  Y-axis motion bias.
+
+## Fixtures
+
+- `fixtures/mini-fan-analysis.json` - representative model output used to verify
+  deterministic scene geometry.

docs/features/annotated-photo-fallback.md

@@ -0,0 +1,284 @@
+# Annotated-Photo Fallback: Image Sizing and Annotation Accuracy
+
+Review date: 2026-06-14. Scope: one user report — when the **annotated-photo
+fallback** triggers (instead of the 3D cutaway), the uploaded image is "too
+large to display," and the annotation placement should be confirmed accurate.
+
+This document is findings + next steps for Codex to implement. It does **not**
+authorize any deployment or Hugging Face changes on its own; follow the normal
+GitHub → HF sync and verification flow in `AGENTS.md`. All file/line references
+are to `index.html` unless noted.
+
+---
+
+## TL;DR
+
+1. **The image-sizing bug is real and confirmed in a browser.** The
+   annotated-photo image renders at its **intrinsic aspect height at full panel
+   width**, ignoring the viewport height, so tall photos overflow the viewport
+   by ~2x. `object-fit: contain` never engages because the box it should fit
+   inside is itself oversized.
+2. **Root cause:** nested `display: grid; place-items: center` containers
+   (`.annotated-stage` → `.annotation-frame`) with auto-sized rows. A child's
+   `height: 100%` resolves against an *auto* (content-sized) grid row, not the
+   container's pixel height, so it collapses back to the image's natural size.
+3. **The annotation accuracy is mostly broken *as a side effect* of the sizing
+   bug** — labels are positioned against the oversized, overflowing image box,
+   so any callout in the lower half of a tall photo lands below the visible
+   viewport and is clipped. Fixing the sizing fixes most of the misplacement.
+   A few annotation-accuracy improvements remain that are independent of sizing
+   (no marker dot at the point, edge-clamp detaches labels, unused `box`).
+
+---
+
+## How this was verified (not just code inspection)
+
+I reproduced the exact `buildAnnotatedPhoto` DOM (`index.html:996-1076`) and the
+exact CSS rules (`.fallback-stage`/`.annotated-stage`/`.annotation-frame`/
+`.annotation-image`, `index.html:466-511`) in a standalone page, loaded a
+**3000 × 4000 portrait** test image into a **900 × 600** viewport pane, and
+measured the rendered geometry in a real browser (Chromium via Playwright):
+
+| Scenario | Image rendered (W×H) | Fits 600px-tall pane? |
+| --- | --- | --- |
+| **Current code (baseline)** | **864 × 1151** | ❌ overflows (image bottom at 1209px) |
+| Fix: pin image absolutely to padded box | 864 × 498 | ✅ contained (top 58 → bottom 556) |
+| Fix: definite `minmax(0,1fr)` tracks at **both** grid levels | 864 × 498 | ✅ contained |
+
+`864 = 900 − 18px×2` (panel width minus horizontal padding); `1151 ≈ 864 ×
+(4000/3000)` — i.e. the image is laid out at panel width and natural aspect,
+with **zero** vertical constraint. That is the "too large to display" symptom.
+(The repro page was temporary and has been removed; re-create it if you want to
+re-measure.)
+
+---
+
+## Root cause (precise)
+
+The fallback markup is three nested boxes:
+
+```
+#viewport (absolute, inset:0)                       <- definite size, good
+└─ .fallback-stage.annotated-stage                  index.html:1011-1012
+     position:absolute; inset:0                      (definite height ✔)
+     display:grid; place-items:center; padding:58/18/44   index.html:490-495
+   └─ .annotation-frame                              index.html:1013-1014
+        width:100%; height:100%                       index.html:497-503
+        display:grid; place-items:center               <-- second nested grid
+      ├─ img.annotation-image                         index.html:1015-1018
+      │    width:100%; height:100%; object-fit:contain  index.html:505-511
+      └─ .label-layer (absolute, inset:0)
+```
+
+Two compounding CSS facts:
+
+- **`place-items: center` sets `align-items: center`, not `stretch`.** Combined
+  with the default `grid-auto-rows: auto`, the single grid row is **content
+  sized**, not stretched to the container's definite height.
+- **A percentage `height` resolves against the grid *area* (the track), and an
+  `auto` track is *indefinite*.** So `height: 100%` on a child of a
+  `place-items: center` grid computes as `auto`.
+
+This happens **twice**:
+
+1. `.annotation-frame { height: 100% }` inside `.annotated-stage` →
+   the frame's track is auto → frame height becomes auto.
+2. `img.annotation-image { height: 100% }` inside `.annotation-frame` →
+   the image's track is auto → image height becomes auto → the `<img>` uses its
+   intrinsic aspect ratio at the available width (864px) → 1151px tall.
+
+Measured proof that the bug is the **inner** grid too: even after forcing
+`.annotation-frame` to a correct definite 498px box, the image still rendered
+1151px, because its `height:100%` resolves against `.annotation-frame`'s *inner
+auto row*, not the frame's element box. Both grid levels must be fixed (or the
+nested-grid sizing dropped entirely).
+
+> Note: `.source-image` in the side panel (`index.html:384-390`) does **not**
+> have this bug because it has a fixed `height: 180px` — a definite height, so
+> `object-fit: contain` works there. The viewport fallback wants to fill
+> available space rather than a fixed height, which is why it hit the trap.
+
+---
+
+## Fix options (both verified to contain the image at 864 × 498)
+
+Pick one. **Option A is recommended** — fewest moving parts, no dependence on
+fragile nested-grid percentage resolution.
+
+### Option A (recommended): pin the image to the padded content box
+
+Stop relying on `height: 100%` chaining through two grids. Make the image fill a
+single absolutely-positioned box and let `object-fit: contain` do the framing.
+
+```css
+/* .annotated-stage can keep its background; drop the grid centering */
+.annotation-frame {
+  position: absolute;
+  inset: 58px 18px 44px;     /* same as the old .annotated-stage padding */
+  /* remove width/height:100% + display:grid + place-items:center */
+}
+.annotation-image {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: contain;       /* now fits a definite box -> letterboxed, contained */
+}
+```
+
+`.label-layer` already is `position:absolute; inset:0` (`index.html:466-471`),
+so it keeps lining up with the frame. The `58/18/44` padding currently lives on
+`.annotated-stage` (`index.html:493`); move that inset onto `.annotation-frame`
+(or keep the padding on the stage and set `.annotation-frame { position:absolute;
+inset:0 }`). Either way the frame becomes a **definite** box and the image is
+contained.
+
+### Option B: keep the grids but make every track definite
+
+If you prefer to keep `display:grid` centering, the breakage is the auto rows —
+give **both** grids definite tracks and let the items stretch:
+
+```css
+.annotated-stage {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  grid-template-rows: minmax(0, 1fr);
+  place-items: stretch;          /* not center: stretch the frame to fill */
+  padding: 58px 18px 44px;
+}
+.annotation-frame {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  grid-template-rows: minmax(0, 1fr);
+  min-width: 0;
+  min-height: 0;
+  width: auto;                   /* track sizing handles it; 100% no longer needed */
+  height: auto;
+}
+.annotation-image { width: 100%; height: 100%; object-fit: contain; }
+```
+
+This also measured 864 × 498, contained. It is more brittle (relies on readers
+understanding the `minmax(0,1fr)` + `min-height:0` idiom), hence Option A is
+preferred.
+
+> Whichever option: this is **CSS-only**. No change to `buildAnnotatedPhoto`'s
+> JS, the schema, the backend, or `app.py` is required for the sizing fix.
+
+---
+
+## Annotation accuracy
+
+### A) Most misplacement is a *symptom* of the sizing bug — fixing sizing fixes it
+
+`updatePhotoLabels` (`index.html:1031-1062`) positions each callout from:
+
+- `containedImageRect(image)` (`index.html:1096-1118`) — computes the
+  letterboxed sub-rect of the image from `image.naturalWidth/Height` and the
+  `<img>` bounding box, then
+- `label.left = imageRect.left − layerRect.left + point[0] * imageRect.width`
+  (and the `point[1]` equivalent for top), clamped to the layer.
+
+This math is **correct** *only when the `<img>` box matches the visible image
+area*. With the current sizing bug the `<img>` box is 864 × 1151 and overflows
+the viewport, so:
+
+- `imageRect.width/height` come from the oversized box, so a `point[1] = 0.8`
+  callout is placed at ~0.8 × 1151 ≈ 920px down — **far below** the 600px
+  viewport, which is `overflow: hidden` (`.viewport-pane`, `index.html:105`), so
+  the label is clipped and the user never sees it.
+- The clamp uses `layerRect.height` (also 1151), so the "keep on screen" clamp
+  (`index.html:1044-1047`) clamps to the wrong, oversized bounds.
+
+**Once the image is contained (Option A/B), `containedImageRect` returns the
+real letterboxed rect and the existing placement math is accurate.** So the
+sizing fix is also the primary annotation-accuracy fix. Re-verify after fixing.
+
+### B) Independent annotation-accuracy improvements (do after the sizing fix)
+
+**User decision (2026-06-14): in scope — implement sizing fix *and* this
+annotation-accuracy polish.** Do items #1–#3 below; #4 (1px border) and #5
+(coercion clamp) are optional robustness items, implement if cheap.
+
+1. **No marker at the actual point.** The callout box is centered *on* the point
+   via `.scene-label { transform: translate(-50%, -50%) }` (`index.html:476`),
+   so the text occludes the component instead of pointing at it, and an
+   edge-clamped label has nothing tying it back to the real location. Recommend
+   drawing a small dot/crosshair at the exact `point` (a 1–2px element, not
+   transformed) and offsetting the text label, optionally with a short leader
+   line. Numbered prefixes already exist (`(index + 1) + ". "`,
+   `index.html:1051`) but there's no matching number on the photo, so the number
+   is currently meaningless spatially.
+
+2. **Edge clamp silently detaches the label from its point.** `Math.min(width −
+   72, Math.max(72, …))` (`index.html:1040-1047`) keeps the label on screen but,
+   with no leader/marker (see #1), a clamped label no longer indicates which
+   component it describes. The marker dot from #1 is the fix — keep the *dot* at
+   the true (clamped-to-image) point and only clamp the *text*.
+
+3. **`annotation.box` is parsed and validated but never drawn.** The schema and
+   coercion carry an optional normalized `box: [x, y, w, h]`
+   (`snap2sim/schema.py:197-202`, `snap2sim/model_io.py:325-327`), but
+   `buildAnnotatedPhoto` ignores it. When present, drawing the bounding box over
+   the contained image would be a much stronger, more accurate annotation than a
+   single point. Optional enhancement.
+
+4. **1px border offset.** `.annotation-image` has a `1px` border
+   (`index.html:509`) and `box-sizing: border-box` is global (`index.html:38-40`),
+   so `object-fit: contain` fits the *content* box (inside the border) while
+   `containedImageRect` measures the *border* box — a 1px placement error.
+   Negligible; mention only. If you want it exact, account for the border or use
+   `outline` instead of `border`.
+
+5. **Coercion rejects (drops) out-of-range points instead of clamping.**
+   `_unit_number_list` returns `None` if any coordinate is outside `[0,1]`
+   (`snap2sim/model_io.py:311-315`), so a point like `[1.02, 0.5]` discards the
+   *entire* annotation and the part may then fall through to "unavailable". The
+   browser already `clamp01`s at render (`index.html:1120-1122`), so consider
+   clamping (not rejecting) server-side for resilience. Minor robustness item;
+   the prompt already asks for `[0,1]` (`snap2sim/prompts.py:31-34`).
+
+The point-coordinate contract itself is consistent end-to-end: normalized
+`[0,1]`, **origin top-left**, asserted in the prompt (`snap2sim/prompts.py:31-34`)
+and consumed as `point[0]→x*width`, `point[1]→y*height` from the image's
+top-left (`index.html:1040-1047`). No change needed there.
+
+---
+
+## Security / invariants to preserve
+
+- This is a client-side CSS/JS change to an existing render path; keep the
+  "no model-authored HTML" rule from `AGENTS.md`/`SECURITY.md`. `label`/`note`
+  must stay `textContent`, never `innerHTML` (already correct,
+  `index.html:1051-1058`). A new marker-dot/box element must be built with
+  `document.createElement` + style, not injected markup.
+- Keep using the **local** `currentPreviewUrl` object URL for the photo
+  (`index.html:1018`, `index.html:1134-1139`); do not round-trip the image back
+  from the server for display.
+- No change to rate limiting, upload caps, or decompression-bomb guards in
+  `app.py` is required.
+
+---
+
+## Suggested implementation order for Codex
+
+1. **Sizing fix first (Option A).** CSS-only in `index.html`. This is the bug
+   the user reported and it also corrects most annotation placement.
+2. **Re-verify in a real browser** with both a **tall (portrait)** and a **wide
+   (landscape)** photo that triggers the annotate fallback: the whole image is
+   visible and contained, no viewport overflow/scroll, and callouts land on the
+   correct components within the image (especially lower-half points that were
+   previously clipped). Check the ≤860px stacked layout (`index.html:555-581`).
+3. **Then** the annotation-accuracy items (in scope per the user): marker dot at
+   the true point + offset/leader label (#1, #2), and render `annotation.box`
+   when present (#3). Items #4/#5 optional.
+4. Run the standard local checks per `AGENTS.md` (schema/parser + FastAPI
+   `TestClient` for `/`, `/analyze_image`, `/generate_scene`), then the normal
+   PR → GitHub Actions HF sync → authenticated private-Space verification.
+
+## Resolved scope
+
+- **Sizing fix + annotation-accuracy polish are both in scope**
+  (user decision, 2026-06-14): the CSS sizing fix, marker dots at the true
+  point, offset/leader labels, and rendering `annotation.box` when the model
+  provides it.

FEATURE.md → docs/features/confidence-threshold.md

@@ -1,4 +1,4 @@
-# FEATURE: Confidence Threshold — Apply Only at Analysis & Generation
+# Confidence Threshold: Apply Only at Analysis and Generation
 
 Status: **Implemented and synced to the private Space, June 14, 2026.**
 Supersedes the prior implemented version of this file (commit `a0540e9`,
@@ -179,7 +179,8 @@ accessible (don't regress the existing `aria-live` label).
   only while a request is in flight, and re-enabled afterward.
 - **Accessibility/layout (regression):** slider keyboard-operable, `#thresholdValue`
   announced, does not block canvas OrbitControls (the pointer-events bug fixed in
-  the REVIEW2.md pass), and no mobile horizontal overflow.
+  the `docs/reviews/interaction-and-fallback-review.md` pass), and no mobile
+  horizontal overflow.
 - `INFERENCE_BACKEND=local` sample mode still renders the example analysis with
   the slider present and the threshold honored at generation.
 - Existing local checks pass: schema/parser checks and FastAPI `TestClient` for

docs/features/renderer-vocabulary.md

@@ -0,0 +1,314 @@
+# Renderer Vocabulary: Richer Geometry, Motion, and Part Counts
+
+Review date: 2026-06-14. Reviewer: Claude (Opus 4.8), for OpenAI Codex to
+implement. Scope: one user goal — the vision prompt should be **more concise and
+descriptive**, and the pipeline should give the model **more freedom over the
+built-in Three.js geometry/motion vocabulary** and a **larger range of parts**.
+
+This document is findings + next steps. It does **not** authorize any deployment
+or Hugging Face changes on its own; follow the normal GitHub → HF sync and
+verification flow in `AGENTS.md`. File/line references are to the repo state at
+review time.
+
+User decisions captured for this spec (2026-06-14):
+
+- **Shapes:** add the *high-value set* — `cone`, `capsule`, `torus`, and a
+  `spring` (helix) builder — on top of the existing 5.
+- **Motions:** add `screw` (helical: rotate + translate together), `orbit`
+  (revolve around a pivot point), and `pulse` (scale breathing) on top of the
+  existing 4.
+- **Parts:** raise the usable cap to **6** (the renderer already allows 6).
+
+---
+
+## TL;DR — the one architectural fact that drives everything
+
+**The prompt cannot grant freedom the renderer doesn't already have.** Because of
+the hard security invariant — *no model-authored HTML; render deterministically
+from validated JSON* (`AGENTS.md` Runtime Notes, `SECURITY.md` Agent Guidance,
+`docs/reviews/security-hardening.md` §3) — the only things that can appear on
+screen are shapes/motions
+that the **browser renderer** explicitly builds in `buildPartMesh`
+(`index.html:1141`) and `applyMotion` (`index.html:1195`).
+
+So today the vocabulary is capped **identically in four places**, and any
+expansion must change all four *in lockstep* (renderer is the source of truth):
+
+| Layer | Shapes | Motions | Parts cap |
+| --- | --- | --- | --- |
+| Prompt (`snap2sim/prompts.py:26-27`, `:32`) | box, cylinder, sphere, gear, rod | rotate, translate, oscillate, static | "2 to 4" |
+| Schema enum (`snap2sim/schema.py:136-139`, `:165-169`, `:214-215`) | same 5 | same 4 | no max |
+| Coercion (`snap2sim/model_io.py:166`, `:169`, `:117`) | same 5 (else→box) | same 4 (else→static) | `parts[:4]` |
+| Renderer (`index.html:842`, `:1145-1156`, `:1202-1210`, `:929`) | same 5 (else→box) | same 4 | `slice(0,6)` |
+
+Two consequences:
+1. **Parts is already inconsistent**: renderer renders 6, but the prompt asks for
+   ≤4 and coercion truncates to 4. Raising the usable count to 6 is mostly
+   removing an artificial cap (see §3).
+2. **Adding shapes/motions is a 4-layer change**, not a prompt edit. The order
+   that avoids a broken intermediate state is: **renderer → schema → coercion →
+   prompt** (build the capability, allow it, coerce toward it, then ask for it).
+
+---
+
+## Finding 1 — The prompt is verbose and under-describes the vocabulary it already has
+
+`build_vision_prompt` (`snap2sim/prompts.py:13-56`) is ~40 lines and embeds a
+full JSON skeleton, but:
+
+- It lists shapes/motions as **bare enums** (`prompts.py:26-27`) with **zero
+  guidance on when to use each**. The model gets `box, cylinder, sphere, gear,
+  rod` and must guess mapping. In practice the example payload
+  (`EXAMPLE_ANALYSIS`, `schema.py:11-110`) only ever uses box/cylinder/gear, so
+  `sphere` and `rod` are effectively invisible to the model. The vocabulary is
+  underused before we even expand it.
+- It repeats constraints (e.g. "compact", "physically plausible", "short" appear
+  multiple times across `:15-18`, `:31`, and the example) and spends many lines
+  re-stating field rules already enforced by `schema.py` / coerced by
+  `model_io.py`.
+- `VISION_SYSTEM_PROMPT` (`prompts.py:5-10`) is terse and doesn't frame the
+  model's strengths (it's a *Reasoning* GGUF per `AGENTS.md`) or the "annotated
+  cutaway" product goal.
+
+**Net:** the prompt is long on rules and short on *descriptive guidance*, which
+is the opposite of what helps a reasoning model pick good primitives.
+
+**A cheap win exists independent of any renderer change:** add a terse
+"shape → use for" and "motion → use for" guide so the model exploits the
+existing 5/4 vocabulary. That guide then grows naturally when we add the new
+primitives.
+
+---
+
+## Finding 2 — High-value Three.js primitives are unused; the cutaway aesthetic wants them
+
+The renderer hand-builds geometry in `buildPartMesh` (`index.html:1141-1167`)
+and `gearGeometry` (`index.html:1169-1187`). Three.js ships many more primitives
+that map cleanly onto real mechanism elements. The user picked the **high-value
+set**:
+
+| New shape | Three.js primitive | Real mechanism elements it covers |
+| --- | --- | --- |
+| `cone` | `ConeGeometry(radius, height, seg)` | valve cones, drill/screw tips, springs' seats, nozzles, pawl points |
+| `capsule` | `CapsuleGeometry(radius, length, …)` | pistons, dowel pins, rollers, bearings, plungers, shafts with rounded ends |
+| `torus` | `TorusGeometry(radius, tube, …)` | o-rings, retaining/snap rings, coils, washers (thick), seals |
+| `spring` | custom helix via `TubeGeometry` + `CatmullRomCurve3` (like `gearGeometry` is custom) | compression/extension springs, coils, helical elements — *very* common and currently impossible to depict |
+
+> Note on a latent inconsistency to clean up while here: the current `cylinder`
+> branch (`index.html:1146`) already secretly supports a **cone/taper** by using
+> `size[0]/2` as top radius and `size[2]/2` as bottom radius — but `size` is
+> documented everywhere else as `[x, y, z]` extents, and nothing tells the model
+> this. Introducing an explicit `cone` shape (with its own `size` semantics)
+> removes the need for that undocumented trick. Decide whether `cylinder` should
+> revert to a true cylinder (`radiusTop == radiusBottom`) once `cone` exists;
+> recommended yes, to keep `size` semantics consistent.
+
+### `size` semantics for the new shapes (must be documented in the prompt)
+
+Keep the existing convention: `size: [x, y, z]` are bounding extents, and the
+builder derives radii/lengths from them so the model never has to send
+`radius`/`height` (which the prompt already forbids, `prompts.py:28-30`). Proposed:
+
+- `cone`: base diameter from `max(x, z)`, height from `y`. Apex +y.
+- `capsule`: diameter from `max(x, z)`, total length from `y` (long axis +y;
+  reuse the `rod` pattern if a horizontal default reads better — match `rod`'s
+  `rotateX` convention at `index.html:1151` for consistency).
+- `torus`: outer diameter from `max(x, z)`, tube thickness from `y` (clamp tube
+  to a fraction of radius so it stays a ring, not a sphere).
+- `spring`: outer diameter from `max(x, z)`, length/height from `y`; expose
+  `coils` (int, like `teeth` for gear, `schema.py:158`) and an optional
+  `wire` thickness with sane defaults.
+
+All four must also be reachable through the same `color`, `rotation`, and
+`position` handling that already wraps `buildPartMesh`
+(`index.html:929-940`, color at `index.html:1158`/`colorFor` `:1228`).
+
+---
+
+## Finding 3 — Parts cap is artificially low and inconsistent
+
+- Prompt says **"Use 2 to 4 parts"** (`prompts.py:32`).
+- Coercion truncates with **`parts[:4]`** (`model_io.py:117`).
+- Renderer already maps **`slice(0, 6)`** (`index.html:929`) and labels project
+  per mesh (`updateLabels`, `index.html:1213`).
+- Schema imposes **no max** on `parts` (`schema.py:123-125`).
+
+**Decision: usable cap = 6.** This is mostly *removing* a cap:
+
+- Prompt: change "Use 2 to 4 parts" → "Use **2 to 6** parts; prefer the fewest
+  that explain the mechanism" (`prompts.py:32`).
+- Coercion: `parts[:4]` → `parts[:6]` (`model_io.py:117`).
+- Renderer: already 6 — no change, but double-check label legibility / overlap at
+  6 parts (`updateLabels` clamps at `index.html:1221-1222`).
+- Schema: optionally add `"maxItems": 6` to the `parts` array
+  (`schema.py:123`) so over-long payloads fail validation predictably instead of
+  being silently truncated only on the coercion path (note: `model_io.py` runs
+  only on the Modal path, per `docs/reviews/interaction-and-fallback-review.md`;
+  the Space `validate_analysis` path
+  does **not** truncate, so a schema `maxItems` keeps both paths consistent).
+
+---
+
+## Finding 4 — Motions are hand-coded, not "built-in"; expand the custom set
+
+`applyMotion` (`index.html:1195-1211`) implements all motion by hand: `rotate`
+(continuous spin on `axis`), `oscillate` (sinusoidal rotation), `translate`
+(sinusoidal slide along `axis` within `range`), `static`. Three.js has no
+"motion" concept of its own, so "more built-in motions" = **add more primitives
+to `applyMotion`**. User picked:
+
+| New motion | Behavior | Mechanism examples | Params (extend schema) |
+| --- | --- | --- | --- |
+| `screw` | rotate **and** translate along the same `axis` together (helical) | screws, lead screws, drill bits, augers, twist mechanisms | reuse `axis`, `speed`, `phase`, `range` (translate extent) + e.g. `pitch` |
+| `orbit` | revolve the part **around a pivot point** (not its own center) | planetary/idler gears, cranks, eccentrics, governor weights | `axis`, `speed`, `phase` + a `pivot: [x,y,z]` |
+| `pulse` | sinusoidal **scale** breathing | diaphragms, bladders, pumps, bellows, valves opening/closing | `speed`, `phase`, `amplitude` |
+
+Implementation notes for `applyMotion`:
+
+- It already resets to base each frame (`mesh.position.copy(basePosition)`,
+  `mesh.rotation.copy(baseRotation)`, `index.html:1200-1201`) — good; `screw` and
+  `orbit` can compose translate+rotate cleanly on top of that.
+- `orbit` needs the pivot in world space; store it on `mesh.userData` at build
+  time like `basePosition` (`index.html:936`). Offset = position − pivot, rotate
+  the offset by `axis`, re-add pivot.
+- `pulse` should multiply the **reveal** scale (`revealMesh`, `index.html:1189`)
+  rather than fight it — guard so the staggered reveal still plays first.
+- Keep the existing param defaults pattern (`speed||1`, `phase||0`,
+  `amplitude||0.25`, `range||[-0.25,0.25]`, `index.html:1197-1207`).
+
+Schema additions: extend the `motion` enum (`schema.py:165-169`, `_MOTIONS`
+`:215`) and add optional `pitch` (number) and `pivot` (3-number list) to the
+`motion` properties (`schema.py:162-186`), validated with the existing
+`_require_number_list` helpers (`schema.py:326-329`). Coercion: extend the
+allowed set (`model_io.py:169`) and carry the new params through (mirror
+`_axis_vector`, `model_io.py:173-175`, `:290`).
+
+---
+
+## Finding 5 — The renderability gate and validators must learn the new vocabulary too
+
+Three guards currently encode the old vocabulary and will silently reject or
+downgrade the new shapes if missed:
+
+1. **Browser renderability check** (`index.html:840-844`): the
+   `["box","cylinder","sphere","gear","rod"].includes(geometry.shape)` test
+   decides whether a part counts as renderable (feeds `render_mode` /
+   annotate-fallback selection, `schema.py:select_render_mode`). Add the new
+   shapes here or a part with `shape:"spring"` will be treated as non-renderable
+   and fall back to annotate-only.
+2. **Schema validator** (`schema.py:_SHAPES` `:214`, `_MOTIONS` `:215`, enums
+   `:136-139`/`:165-169`) — extend both sets/enums.
+3. **Coercion fallbacks** (`model_io.py:166-167`, `:169-170`) — extend the
+   allowed sets so a valid new shape isn't rewritten to `box`/`static`.
+
+Also update `EXAMPLE_ANALYSIS` (`schema.py:11-110`) to exercise at least a couple
+of the new primitives (e.g. a `spring` and a `capsule`) so the in-prompt example
+actually demonstrates the wider vocabulary — the example is the single biggest
+lever on what the model emits.
+
+---
+
+## Proposed prompt rewrite (concise + descriptive)
+
+Goal: **shorter scaffolding, richer guidance.** Two concrete changes.
+
+### A) `VISION_SYSTEM_PROMPT` (`prompts.py:5-10`) — frame the task and the model
+
+Keep it ~4 lines but add: this is a *reasoning* model building an **annotated
+technical cutaway**; reason briefly, then emit one JSON object; prefer the
+*simplest set of primitives* that truthfully explains the mechanism; lower
+confidence + annotate when unsure (already the policy — keep it).
+
+### B) `build_vision_prompt` (`prompts.py:13-56`) — trim rules, add a vocabulary guide
+
+- **Cut redundancy**: state "final answer = one JSON object, no markdown" once;
+  drop repeated "compact/short/plausible" restatements.
+- **Replace bare enums with a terse guide** the model can act on, e.g.:
+
+  ```
+  Shapes (pick the closest; size = [x,y,z] extents):
+    box       plates, housings, blocks, levers, selectors
+    cylinder  shafts, sleeves, bushings, drums, pins
+    cone      valve cones, tips, nozzles, tapers
+    capsule   pistons, rollers, dowel pins, plungers, bearings
+    sphere    balls, detents, ball bearings, nodes
+    rod       links, tie rods, thin axles, connecting rods
+    gear      toothed wheels (set teeth); ratchets, cogs
+    torus     o-rings, snap/retaining rings, seals, coils (single)
+    spring    helical springs, coils (set coils)
+
+  Motions (axis is a numeric vector like [0,1,0]):
+    static    fixed structure / housing
+    rotate    continuous spin (speed)
+    oscillate sinusoidal twist (amplitude, speed)
+    translate slide along axis (range [min,max])
+    screw     spin + advance along axis together (pitch) — screws, drills
+    orbit     revolve around a pivot point (pivot [x,y,z]) — planetary/cranks
+    pulse     scale breathing (amplitude) — diaphragms, pumps
+  ```
+
+- **Update the part-count line** to "Use 2 to 6 parts; prefer the fewest that
+  explain the mechanism."
+- **Keep** the hard rules that protect parsing/rendering: numeric `size`/
+  `position`/`axis` vectors only, no `radius`/`height`/string-axis
+  (`prompts.py:28-30`), normalized `[0,1]` top-left annotation coords
+  (`prompts.py:31-34`), and "reason first, final answer is one JSON object"
+  (`prompts.py:14-17`, required by the `<think>`-stripping parser,
+  `docs/reviews/interaction-and-fallback-review.md`
+  Q3 / `model_io.py`).
+- **Keep the example** but shrink it to a 2–3 part skeleton that now includes a
+  new primitive, and rely on `EXAMPLE_ANALYSIS` (the schema sample) to show the
+  full shape.
+
+---
+
+## Security / invariants to preserve (do not regress)
+
+- **Deterministic rendering only.** All new shapes/motions are built in
+  `buildPartMesh`/`applyMotion` from validated JSON. **Never** inject
+  model-authored HTML/JS/markup (`AGENTS.md`, `SECURITY.md`,
+  `docs/reviews/security-hardening.md` §3).
+  `label`/`note` stay `textContent` (`index.html:1223`).
+- **Validate before render.** New enum values must be added to `schema.py` so
+  `validate_analysis` (`schema.py:263`) still runs before scene generation; do
+  not loosen validation to "accept anything."
+- **Coercion stays conservative.** Unknown shapes/motions must still fall back to
+  `box`/`static` (`model_io.py:166-170`), never crash.
+- No change required to rate limiting, upload caps, decompression-bomb guards
+  (`app.py`), Modal bearer auth, or the GitHub→HF sync.
+
+---
+
+## Suggested implementation order for Codex
+
+1. **Renderer first** (`index.html`): add `cone`, `capsule`, `torus`, and a
+   `spring` (helix) builder to `buildPartMesh`/a new helper next to
+   `gearGeometry`; add `screw`, `orbit`, `pulse` to `applyMotion`
+   (store `pivot` on `userData`). Update the renderability gate at
+   `index.html:840-844`. Verify each renders before touching Python.
+2. **Schema** (`snap2sim/schema.py`): extend shape/motion enums + `_SHAPES`/
+   `_MOTIONS`; add `pitch`/`pivot`/`coils` properties; optional `parts.maxItems:
+   6`; update `EXAMPLE_ANALYSIS` to use a couple of new primitives.
+3. **Coercion** (`snap2sim/model_io.py`): extend allowed shape/motion sets;
+   carry new params; change `parts[:4]` → `parts[:6]`.
+4. **Prompt** (`snap2sim/prompts.py`): apply the concise rewrite (system + user),
+   the shape/motion guide, and "2 to 6 parts".
+5. **Local verification** (per `AGENTS.md`): schema/parser checks, FastAPI
+   `TestClient` for `/`, `/analyze_image`, `/generate_scene`; and a **real
+   browser** check that each new shape and motion renders and that 5–6-part
+   scenes don't have unreadable overlapping labels.
+6. **Optional Modal re-measure**
+   (`docs/reviews/interaction-and-fallback-review.md` Q3 tuning note): the richer prompt
+   may change token usage; confirm `run_analysis_endpoint_check` still returns
+   valid JSON within the current `4096`/`8192`/`300s` budgets before deploy.
+7. Standard PR → GitHub Actions HF sync → authenticated private-Space
+   verification. Keep the Space **private** unless the user explicitly approves
+   going public (`AGENTS.md`, `SECURITY.md`).
+
+## Open items to confirm with the user (only if they come up during build)
+
+- Whether `cylinder` should revert to a true (untapered) cylinder once explicit
+  `cone` exists (recommended yes — see §2 note).
+- Whether `spring`/`torus` need extra params (`coils`, `wire`/`tube` thickness)
+  exposed to the model or just sensible fixed defaults (recommend defaults first,
+  expose only if visual quality needs it).

docs/features/vision-prompt-roles.md

@@ -0,0 +1,169 @@
+# Vision Prompt Roles: Split System and User Prompt
+
+## Question being answered
+
+> Is it better to split the **analysis** portion and the **generation** portion
+> into different system prompts and user prompts? Would this help the model
+> interpret the input and produce better output?
+
+Short answer: **Yes, split — but split by chat *role* inside the single
+analysis call, not into two model calls.** The "generation" step is not a model
+step in this codebase, so the only useful split is system-vs-user within the one
+vision call. Wiring that up is a small, safe change that aligns the prompt with
+how the instruct/reasoning model was trained.
+
+---
+
+## Findings
+
+### Finding 1 — There is only one model step; "generation" is deterministic
+
+The pipeline is:
+
+```
+image -> [MODEL] vision analysis -> validated JSON -> [NO MODEL] Three.js scene
+```
+
+- Scene rendering is deterministic browser-side Three.js built from the
+  validated analysis JSON (`AGENTS.md:34-35`, `AGENTS.md:196-198`).
+- `InferenceClient.generate_scene` (`snap2sim/backend.py:47-51`) does **no**
+  model inference — it validates the analysis and picks a `render_mode`. Model-
+  authored scene HTML/JS was intentionally removed (`SECURITY.md:96-97`).
+
+**Implication:** "split analysis and generation into different prompts" cannot
+mean *two model calls*. There is no generation model call to separate, and
+adding a second round-trip would double an already slow path (~35s observed,
+`300s` timeout at `modal_app.py:392`) for zero quality gain, since the scene is
+deterministic. **Do not introduce a second inference step.**
+
+### Finding 2 — The system prompt is currently dead code
+
+- `VISION_SYSTEM_PROMPT` (`snap2sim/prompts.py:5-10`) is defined but **never
+  imported or used**. `modal_app.py` imports only `build_vision_prompt`
+  (`modal_app.py:20`).
+- The real call, `run_llamacpp_prompt` (`modal_app.py:291-334`), passes the
+  prompt through a single `-p` flag (`modal_app.py:308-309`). There is **no**
+  system message.
+- Net effect: the model receives one large *user* turn that mixes four different
+  concerns — role framing, the analytical task, the full output schema, and
+  field-by-field formatting rules (`build_vision_prompt`,
+  `snap2sim/prompts.py:12-70`).
+
+So today there is effectively **no** system/user separation, and the one
+"system" string we wrote is doing nothing.
+
+### Finding 3 — The runtime supports a real role split
+
+- `llama-mtmd-cli` accepts a separate system message via `-sys` alongside the
+  user prompt `-p`, and applies the model's chat template. (Confirmed against
+  llama.cpp `mtmd-cli` usage.)
+- The model is `unsloth/NVIDIA-Nemotron-3-Nano-...-Reasoning-GGUF`
+  (`AGENTS.md:20`), an instruct/reasoning model. Such models are trained to
+  treat the **system** turn as persistent role + constraints and the **user**
+  turn as the immediate request. Collapsing everything into the user turn is
+  off-distribution and dilutes the per-request ask.
+
+### Why a role split should help interpretation and output
+
+1. **Aligns with training.** Stable behavior/output-contract belongs in system;
+   the moment-to-moment ask belongs in user. The model already expects this
+   shape.
+2. **Sharpens the ask.** The user turn becomes short and image-focused
+   ("Analyze the component in this photo …") instead of being buried under ~40
+   lines of schema rules.
+3. **Separates invariants from the request.** The schema, shape/motion
+   vocabulary, and hard rules are constant across every image; they read as
+   *policy* in system, not as part of *this* request.
+4. **Stops wasting the role channel.** We already wrote a system prompt; right
+   now it is ignored.
+
+This is a low-risk change: it does not touch the schema, validator, coercion
+(`snap2sim/schema.py`, `snap2sim/model_io.py`), or the deterministic renderer.
+
+---
+
+## Recommendation
+
+**Adopt a system/user role split within the single vision call.** Concretely:
+
+- **System message** = the invariant output contract:
+  - role + reasoning frame (it is a reasoning model; brief reasoning then JSON),
+  - the "emit exactly one JSON object, no markdown" rule,
+  - the JSON skeleton,
+  - the shape -> use-for and motion -> use-for vocabulary guide,
+  - the hard field rules (`size: [x,y,z]`, numeric axis vectors, 2–6 parts, no
+    `radius/height/length/width/depth`).
+- **User message** = only the per-image ask: "Analyze the hardware component in
+  this photo as a cutaway mechanism and return the analysis JSON." (The image is
+  attached via `--image`.)
+
+Keep it one inference call. Keep temperature, token, context, and timeout
+budgets as-is (`modal_app.py:388-394`) — this is a prompt-structure change, not
+a budget change.
+
+---
+
+## Next steps (for Codex to implement)
+
+1. **`snap2sim/prompts.py`**
+   - Repurpose `VISION_SYSTEM_PROMPT` to hold the full invariant contract
+     (role + JSON-only rule + skeleton + shape/motion vocabulary guide + hard
+     field rules) currently living inside `build_vision_prompt`.
+   - Reduce `build_vision_prompt()` to the short per-image ask only. Consider
+     renaming it `build_vision_user_prompt()` (keep a back-compat alias if any
+     diagnostic entrypoint imports the old name).
+   - Optionally add `build_vision_messages()` returning `(system, user)` so call
+     sites have one source of truth.
+
+2. **`snap2sim/prompts.py` (smoke test parity, optional)**
+   - The smoke-test prompt is a separate inline string
+     (`modal_app.py:211-234`). Leave functionally as-is, but it can reuse the
+     same system message for realism. Not required for the demo.
+
+3. **`modal_app.py`**
+   - In `run_llamacpp_prompt` (`:291-334`), add an optional `system_prompt:
+     str | None = None` parameter and append `-sys <system_prompt>` to `cmd`
+     when provided. Verify the exact flag name against the deployed
+     `llama-mtmd-cli` build before relying on it (`-sys`); if the installed
+     build does not accept it, fall back to prepending the system text to `-p`
+     so behavior never regresses.
+   - In `analyze_image_llamacpp_payload` (`:385-400`), pass the new system
+     message + the short user prompt.
+   - Update the diagnostic entrypoints that build the prompt
+     (`run_analysis_raw_check` near `:489`, `run_analysis_endpoint_check`,
+     remote check near `:512`) to use the same two-part prompt so diagnostics
+     match production.
+
+4. **Verify before/after (no regressions, measured improvement)**
+   - Local: schema/parser checks + FastAPI `TestClient` for `/`,
+     `/analyze_image`, `/generate_scene` still pass.
+   - Modal: run `run_analysis_raw_check` and `run_analysis_endpoint_check`
+     against the synthetic target image; confirm strict JSON still parses and
+     latency is comparable. Compare parse success / field quality vs. the
+     current single-`-p` prompt on a few representative real photos before
+     committing the prompt change.
+   - Confirm the flag actually took effect (e.g. inspect that `-sys` is honored,
+     not silently ignored) before trusting the split.
+
+5. **Then deploy** following the normal path (Modal deploy of
+   `analyze_image_llamacpp`, GitHub `main` push, GitHub->HF sync, authenticated
+   private-Space verification), per the existing workflow in `AGENTS.md`.
+
+---
+
+## Explicitly NOT recommended
+
+- **Two separate model calls** (an "analysis" call feeding a "generation"
+  call). There is no model generation step; the scene is deterministic. This
+  would only add latency and a failure mode.
+- **Re-introducing model-authored scene HTML/JS.** Prohibited by
+  `SECURITY.md:96-97` and `AGENTS.md:35`.
+
+## Open question for the user
+
+The recommendation assumes you meant "should the prompt be *structured* into
+system vs user roles" (yes), not "should the app make two separate model
+requests" (no — there is no model generation step). If you specifically wanted
+the model to also generate the scene/animation (re-adding a model generation
+call), that conflicts with the current deterministic-renderer security decision
+and should be discussed separately before implementing.

docs/fixtures/mini-fan-analysis.json

@@ -0,0 +1,105 @@
+{
+    "component": "mini fan",
+    "confidence": 0.95,
+    "summary": "A compact desk fan with a motor-driven rotating blade assembly, wire cage, and plastic base.",
+    "trigger": "power switch",
+    "motion_sequence": [
+      "power on",
+      "blade rotation"
+    ],
+    "parts": [
+      {
+        "id": "rotor",
+        "name": "blade assembly",
+        "role": "rotating element",
+        "geometry": {
+          "shape": "cylinder",
+          "size": [
+            0.12,
+            0.12,
+            0.35
+          ],
+          "position": [
+            0,
+            0,
+            0
+          ]
+        },
+        "motion": {
+          "type": "rotate",
+          "axis": [
+            0,
+            0,
+            1
+          ],
+          "speed": 2
+        },
+        "annotation": {
+          "point": [
+            0.5,
+            0.5
+          ],
+          "label": "hub",
+          "note": "central rotating hub"
+        }
+      },
+      {
+        "id": "cage",
+        "name": "protective cage",
+        "role": "static enclosure",
+        "geometry": {
+          "shape": "torus",
+          "size": [
+            0.55,
+            0.55,
+            0.04
+          ],
+          "position": [
+            0,
+            0,
+            0
+          ]
+        },
+        "motion": {
+          "type": "static"
+        },
+        "annotation": {
+          "point": [
+            0.5,
+            0.5
+          ],
+          "label": "cage",
+          "note": "wire mesh surrounding blades"
+        }
+      },
+      {
+        "id": "base",
+        "name": "stand",
+        "role": "support",
+        "geometry": {
+          "shape": "box",
+          "size": [
+            0.45,
+            0.25,
+            0.2
+          ],
+          "position": [
+            0,
+            -0.15,
+            0
+          ]
+        },
+        "motion": {
+          "type": "static"
+        },
+        "annotation": {
+          "point": [
+            0.5,
+            0.85
+          ],
+          "label": "base",
+          "note": "green plastic base"
+        }
+      }
+    ]
+  }

docs/reviews/interaction-and-fallback-review.md

@@ -0,0 +1,325 @@
+# Interaction and Fallback Review: Camera Control and Fallback Strategy
+
+Review date: 2026-06-14. Scope: two questions raised by the user —
+(1) is the cutaway camera movable, and (2) what should the analysis/generation
+fallback be. This document is findings + next steps for Codex to implement.
+It does **not** authorize any deployment or Hugging Face changes on its own;
+follow the normal GitHub→HF sync and verification flow in `AGENTS.md`.
+
+---
+
+## Question 1 — Is the camera movable?
+
+**Update (2026-06-14): the user reports orbit does NOT work in practice.** The
+`OrbitControls` code *is* present, but a layout bug stops it from receiving input.
+Codex must double-check the camera end-to-end (see root-cause + checklist below),
+not assume it works because the control is instantiated.
+
+The control is wired up in `index.html`:
+- `OrbitControls` is imported and merged onto `window.THREE`
+  (`index.html:19`, `index.html:21`).
+- It is instantiated per scene with damping in `buildDeterministicScene`
+  (`index.html:630-636`): `enableDamping = true`, `target.set(0, 0.1, 0)`.
+- `controls.update()` runs every frame in `animate()` (`index.html:690`), which
+  is required for damping to work, and HTML labels reproject each frame via
+  `updateLabels` (`index.html:692`, `index.html:797-810`), so callouts track the
+  camera as it moves.
+
+### Root-cause (prime suspect): the label layer eats pointer events
+
+`OrbitControls` attaches its listeners to `renderer.domElement` (the canvas),
+but a sibling overlay covers that canvas and swallows the mouse/touch events:
+
+- In `buildDeterministicScene`, `stage.append(mount, labelLayer)`
+  (`index.html:617`) appends `labelLayer` **after** `mount`, so it paints on top.
+- `.fallback-stage`, `.scene-mount`, and `.label-layer` all use
+  `position: absolute; inset: 0` with no `z-index` (`index.html:357-362`), so
+  `.label-layer` covers the entire viewport, directly over the canvas.
+- `.scene-label` has `pointer-events: none` (`index.html:374`) **but the
+  `.label-layer` container does not.** A plain `<div>` defaults to
+  `pointer-events: auto`, so the layer intercepts every `mousedown`, `wheel`,
+  and touch before it can reach the canvas. OrbitControls therefore never sees a
+  drag or scroll → orbit/zoom/pan appear dead.
+
+**Fix:** add `pointer-events: none` to `.label-layer` (keep it on `.scene-label`,
+which is already correct). The labels are non-interactive, so this is safe.
+
+### Camera verification checklist for Codex
+
+Do not close this out on code inspection alone — verify in a real browser:
+
+1. Apply the `.label-layer { pointer-events: none; }` fix and confirm
+   left-drag orbits, wheel zooms, right-drag pans.
+2. Confirm `window.THREE.OrbitControls` is actually defined at the moment
+   `buildDeterministicScene` runs (the `type="module"` import at
+   `index.html:17-22` is deferred; if a payload could render before that module
+   executes, `controls` would be `null` and the camera would be locked —
+   `index.html:630-632` already guards with a null check, so a missing import
+   fails silently to a static camera).
+3. Confirm no other overlay intercepts events after load: `.drop-zone`
+   (`index.html:93-117`) must be `hidden` once a scene renders
+   (`resetScene` does this at `index.html:569`), and `.viewport-pane::after`
+   /`.scan-line` are already `pointer-events: none` (`index.html:84`,
+   `index.html:129`).
+4. Verify on touch / the ≤860px layout (`index.html:388-404`).
+
+Once orbit is confirmed working, apply the polish below. **Recommended polish
+(low risk, no backend change):**
+
+- **Distance clamps.** Set `controls.minDistance` / `controls.maxDistance`
+  (and optionally `maxPolarAngle`) so users can't zoom inside a mesh or fly
+  under the grid and lose the model.
+- **Reset-view control.** Add a small "Reset view" tool button next to
+  `Play`/`Load` (`index.html:411-414`) that restores `camera.position` and
+  `controls.target` to the defaults (`camera.position.set(5.4, 3.9, 6.2)`,
+  target `(0, 0.1, 0)`). Store the defaults once so reset is exact.
+- **Affordance hint.** Briefly show a "Drag to orbit · scroll to zoom" hint on
+  first cutaway, or a persistent muted caption in the viewport. Nothing today
+  tells the user the scene is interactive.
+- **Touch / mobile.** `OrbitControls` supports touch by default, but verify on
+  the ≤860px layout (`index.html:388-404`) that one-finger orbit / two-finger
+  zoom don't fight page scroll; set `controls.touches` and/or
+  `renderer.domElement.style.touchAction = "none"` if they do.
+- **Accessibility gap.** `#viewport` is `aria-hidden="true"` (`index.html:415`).
+  That's defensible for a canvas, but the interactive camera is then invisible
+  to assistive tech. Pair the visual hint with the existing screen-reader status
+  region, and ensure the textual readout panel remains the accessible source of
+  truth for part names/roles.
+
+**Bottom line:** do not "add" a movable camera — it exists. Implement the polish
+items above so the existing capability is obvious and bounded.
+
+---
+
+## Question 2 — What should the fallback be?
+
+**User decision (2026-06-14): the fallback should annotate the uploaded photo**
+— labeled callouts on each visible component plus a short description — instead
+of always showing a fixed/generic 3D scene.
+
+### Current behavior (the "fixed value" today)
+
+There are two distinct fallback paths, both of which ignore or only loosely
+relate to the actual photo:
+
+1. **Local / demo mode** (`INFERENCE_BACKEND=local`, which is what the HF Space
+   currently runs). `InferenceClient.analyze_image` returns the **fixed**
+   `EXAMPLE_ANALYSIS` ratchet-wrench payload for *every* image
+   (`snap2sim/backend.py:36-45`, `snap2sim/schema.py:10-89`). So in the live
+   demo, uploading a photo of anything renders the same ratchet cutaway. This is
+   the misleading "fixed value" the user is reacting to.
+2. **Modal real-model mode.** `analyze_image_llamacpp_payload` runs the model,
+   then on parse failure calls `coerce_analysis_response`
+   (`modal_app.py:380-394`). Worst case that bottoms out in `_generic_analysis`
+   — a generic housing/rotor/guide 3D scene (`snap2sim/model_io.py:46`,
+   `snap2sim/model_io.py:170-204`). Still a fixed-ish 3D primitive not tied to
+   the image.
+
+Note: `snap2sim/model_io.py` (parse/coerce) is **only** used by `modal_app.py`.
+The Space-side `app.py` → `backend.py` path does not call it, so coercion never
+runs in the local placeholder path. Keep this in mind when wiring the new
+fallback so it actually triggers on the deployed Space.
+
+### Target behavior — annotated-photo fallback
+
+When a confident, per-image 3D mechanism can't be produced, render the user's
+**own photo** with numbered callouts on each identified component and a text
+description of what it is / how it likely works. This is honest about
+uncertainty and never shows an unrelated mechanism.
+
+Decision logic the browser should follow (in `index.html`):
+1. **Full success** — valid analysis with parts *and* usable primitive geometry
+   → render the interactive 3D cutaway (current path, with the camera polish
+   from Q1).
+2. **Annotated-photo fallback** — model identified components and gave 2D image
+   locations, but 3D geometry/motion is missing or low-confidence → overlay
+   callouts on the source photo + descriptions. **This is the new default
+   fallback.**
+3. **Last resort** — nothing usable at all → keep a clearly-labeled, honest
+   "couldn't analyze" state (retry affordance already exists at
+   `index.html:427`, `index.html:530-531`). Do **not** silently fall back to the
+   fixed ratchet scene.
+
+### Why the schema must change first
+
+The annotated-photo view needs **2D image coordinates per component**, which the
+current contract does not carry. The analysis schema only has 3D
+`geometry.position` (`snap2sim/schema.py:92-169`) — that's world-space for
+Three.js, not pixel space on the photo. Implement in this order:
+
+1. **Extend the schema** (`snap2sim/schema.py`): add an optional per-part
+   `annotation` object, e.g.
+   `{"point": [x, y], "box": [x, y, w, h]?, "label": str, "note": str}` with
+   `point`/`box` in **normalized [0,1] image coordinates**. Make it optional so
+   existing 3D-only payloads still validate. Add validation helpers mirroring the
+   existing `_require_number_list` style, and bound coordinates to [0,1].
+2. **Update the prompt** (`snap2sim/prompts.py`): instruct the model to include
+   `annotation.point` (and `note`) per part when it can locate the component in
+   the image, in normalized coordinates with origin at top-left. Keep the
+   "JSON only, no markdown, no `<think>`" constraints already there.
+3. **Update parsing/coercion** (`snap2sim/model_io.py`): carry `annotation`
+   through `_coerce_part`; treat missing/invalid annotations as simply absent
+   (don't fail the whole part). Decide the fallback trigger: e.g. if a part has a
+   valid `annotation` but no usable `geometry`, mark the payload as
+   "annotate-only" so the browser picks path 2. A top-level `render_mode` hint
+   (`"three"` vs `"annotate"`) returned by `generate_scene` is the cleanest
+   signal — `generate_scene` already returns `{"renderer": ..., "analysis": ...}`
+   (`snap2sim/backend.py:47-49`), so extend that envelope rather than inventing a
+   new channel.
+4. **Browser render path** (`index.html`): add a `buildAnnotatedPhoto(analysis)`
+   alongside `buildDeterministicScene` (`index.html:597`). Reuse the existing
+   source-photo capture — the upload is already shown via `showSourcePreview`
+   / `currentPreviewUrl` (`index.html:718-723`) — draw the photo into the
+   viewport and position absolutely-placed callouts using the normalized
+   `annotation.point` scaled to the rendered image rect. Reuse the existing
+   `.scene-label` styling (`index.html:364-375`) for visual consistency. `Play`
+   should be disabled/hidden in this mode (no animation).
+5. **Demo honesty (local mode):** decide what the placeholder backend does. The
+   fixed ratchet for-every-image (`backend.py:45`) should not remain the live
+   demo experience. Options for Codex to confirm with the user before shipping:
+   either (a) point the Space at the Modal model so real analysis runs, or
+   (b) keep a placeholder but clearly label it "DEMO — sample mechanism, not
+   your photo" so it isn't mistaken for real analysis.
+
+### Validation / security notes (keep the security-hardening pass intact)
+
+- Normalized [0,1] annotation coords are safe to render as positioned DOM, but
+  still **clamp** them client-side (like `updateLabels` already clamps,
+  `index.html:805-806`) and treat `label`/`note` as text (`textContent`, never
+  `innerHTML`) to preserve the "no model-authored HTML" rule from `AGENTS.md`
+  and `docs/reviews/security-hardening.md`.
+- The photo for annotation is the **local** `currentPreviewUrl` object URL; do
+  not round-trip the image back from the server for display.
+- No change to rate limiting, upload caps, or decompression-bomb handling in
+  `app.py` is required for this work.
+
+---
+
+## Question 3 — Let the model think longer / use more token context
+
+**User request (2026-06-14): allow the AI model to think for longer and use more
+token context when it needs to.** The selected model is a *Reasoning* GGUF
+(`unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF`, per `AGENTS.md`),
+so giving it room to reason should improve analysis quality on hard photos.
+
+Current constraints that limit thinking:
+- **The prompt forbids reasoning.** `build_vision_prompt` tells the model "Do not
+  include a reasoning trace or `<think>` tags" (`snap2sim/prompts.py:15-17`), and
+  `VISION_SYSTEM_PROMPT` (`snap2sim/prompts.py:5-9`) is terse. This actively
+  suppresses the reasoning the model was trained for.
+- **Generation budget is small.** `analyze_image_llamacpp_payload` calls with
+  `max_tokens=1536` (`modal_app.py:386`); `run_llamacpp_prompt` default is `1024`
+  (`modal_app.py:292`) and passes it as `-n` (`modal_app.py:307-308`). If the
+  model thinks first, 1536 tokens can be exhausted before the JSON is emitted.
+- **No explicit context window.** The `llama-mtmd-cli` command sets `-n` (output)
+  but never `-c` / `--ctx-size` (`modal_app.py:299-311`), so it falls back to the
+  build default context size. A long `<think>` block plus the multimodal image
+  tokens can overflow the default window and truncate output.
+- **Timeout.** `timeout_seconds=180` at the call site (`modal_app.py:387`) and as
+  the default (`modal_app.py:293`); longer reasoning needs more wall-clock budget.
+
+### Changes to implement (Codex)
+
+1. **Allow reasoning in the prompts** (`snap2sim/prompts.py`): remove the "do not
+   include a reasoning trace or `<think>` tags" instruction and instead permit
+   the model to reason first, then emit the final JSON. Keep the hard requirement
+   that the **final answer is a single JSON object** so parsing still works.
+2. **Strip the reasoning before parsing** (`snap2sim/model_io.py`): add explicit
+   handling to drop any `<think>...</think>` block (and any prose before the JSON)
+   prior to `parse_analysis_response`. The existing `_json_object_candidates`
+   scanner (`snap2sim/model_io.py:53-62`) already searches for balanced `{...}`
+   objects anywhere in the text and tries each candidate, so it is largely robust
+   to a leading reasoning trace — but a `<think>` block can itself contain `{`
+   characters that produce false candidates, so strip it first for reliability.
+   Prefer the **last** complete top-level JSON object when reasoning precedes the
+   answer.
+3. **Raise the generation budget and context window** (`modal_app.py`):
+   - Increase `max_tokens` for analysis (e.g. 1536 → ~3072–4096) at
+     `modal_app.py:386` and/or the `run_llamacpp_prompt` default
+     (`modal_app.py:292`).
+   - Add an explicit `-c` / `--ctx-size` flag to the `llama-mtmd-cli` command
+     (`modal_app.py:299-311`) sized for image tokens + reasoning + JSON
+     (e.g. 8192; confirm against the model card's supported context and Modal GPU
+     memory). Make it a parameter of `run_llamacpp_prompt` with a sensible
+     default so the smoke test and analysis path can differ.
+   - Raise `timeout_seconds` (`modal_app.py:387`, default `modal_app.py:293`) to
+     match the larger budget; the existing `TimeoutExpired` handling
+     (`modal_app.py:317-325`) already surfaces partial output.
+4. **Keep latency acceptable for the demo.** More thinking = slower responses.
+   The browser already shows cold-start language ("WAKING THE WORKSHOP...",
+   `index.html:539`); confirm the front-end `INFERENCE_TIMEOUT_SECONDS`
+   (`snap2sim/backend.py:23`, default 180) and any HF Space/Modal request
+   timeouts are raised in lockstep so longer reasoning doesn't get cut off by an
+   intermediate layer.
+5. **Verify** with `run_analysis_endpoint_check` (`modal_app.py:412`) and the
+   smoke test (`modal_app.py:289`+) that the larger budgets still return valid
+   JSON, then re-run the standard endpoint verification before deploy.
+
+> Tuning note: pick the smallest token/context/timeout values that reliably yield
+> valid JSON on representative photos — over-provisioning context wastes GPU
+> memory and inflates demo latency. Treat the numbers above as starting points to
+> measure, not fixed targets.
+
+---
+
+## Question 4 — Source photo preview is sized/cropped incorrectly
+
+**User report (2026-06-14): the uploaded image is not sized properly in the
+"Source Photo" card.** The preview crops the photo instead of showing it whole.
+
+Cause in `index.html`:
+- `.source-image` uses `width: 100%; max-height: 150px; object-fit: cover`
+  (`index.html:275-281`). `object-fit: cover` **fills and crops** the box, so any
+  portrait or non-matching-aspect photo gets its top/bottom (or sides) clipped —
+  the user can't see the full component they uploaded.
+- There is no fixed/defined preview area, only a `max-height`. With `width: 100%`
+  and no explicit height, the rendered height is aspect-driven and clamped at
+  150px, so wide images shrink while tall images crop — inconsistent framing.
+- The element is `<img id="sourceImage" class="source-image">`
+  (`index.html:432`), populated by `showSourcePreview` via an object URL
+  (`index.html:718-723`); the markup/JS are fine, this is purely a CSS sizing
+  choice.
+
+### Changes to implement (Codex)
+
+1. **Show the whole photo, not a crop.** Switch `.source-image` to
+   `object-fit: contain` (`index.html:277`) so the entire image is visible,
+   letterboxed within the card. The card already has a `--bg` backdrop
+   (`index.html:280`) to fill any letterbox gaps.
+2. **Define a stable preview area.** Give the image (or a wrapping container) a
+   consistent box — e.g. a fixed `height`/`aspect-ratio` plus
+   `width: 100%`, with `object-fit: contain` — so portrait and landscape uploads
+   frame consistently instead of the height jumping per image.
+3. **Consider raising the cap on larger screens.** `max-height: 150px` is small;
+   confirm the chosen size reads well in the right-hand panel
+   (`.source-card`, `index.html:264-273`) and on the ≤860px stacked layout
+   (`index.html:388-404`).
+4. **Verify** with both a tall (portrait) and wide (landscape) photo that the
+   full image is visible and the card doesn't shift layout awkwardly.
+
+---
+
+## Suggested implementation order for Codex
+
+1. **Fix the orbit bug first** (`.label-layer { pointer-events: none; }`) and run
+   the camera verification checklist in a real browser — this is the regression
+   the user actually hit.
+2. Q1 camera polish (self-contained, `index.html` only): distance clamps, reset
+   button, hint, mobile/touch check.
+3. Q4 source-photo preview sizing (`index.html` CSS only): `object-fit: contain`
+   + stable preview box; quick standalone fix.
+4. Schema + prompt + parsing changes for `annotation` and a `render_mode` signal.
+5. `buildAnnotatedPhoto` render path + decision logic in `index.html`.
+6. Q3 model thinking: allow reasoning, strip `<think>`, raise tokens/context/
+   timeouts, keep timeouts aligned across layers.
+7. Resolve the local-demo honesty question (real model vs. labeled placeholder).
+8. Local verification with FastAPI `TestClient` (per `AGENTS.md`), then the
+   standard PR → GitHub Actions HF sync → authenticated Space verification.
+
+## Open items to confirm with the user
+
+- Local-demo behavior (real Modal model vs. clearly-labeled placeholder).
+- Whether the annotated-photo fallback should also offer a manual toggle to the
+  generic 3D cutaway, or replace it entirely (current decision: replace).
+- Final token/context/timeout values for Q3 once Codex has measured latency vs.
+  JSON-validity on representative photos.

docs/reviews/motion-axis-bias.md

@@ -0,0 +1,147 @@
+# Review: Motion Axis Bias Toward [0, 1, 0]
+
+Date: 2026-06-15
+Scope: Does the current prompt (and surrounding pipeline) bias part motion
+toward the world Y axis `[0, 1, 0]`?
+
+## Short answer
+
+Yes. The system prompt nudges the model toward `[0, 1, 0]`, and two
+non-prompt layers (the renderer default and the coercion fallback) push the
+*rendered* result toward Y even harder. The net effect is that uncertain or
+under-specified parts tend to spin/oscillate/slide about world Y regardless of
+their actual geometry orientation.
+
+## Where the bias comes from
+
+### 1. Prompt anchoring (`snap2sim/prompts.py`, `VISION_SYSTEM_PROMPT`)
+
+`[0, 1, 0]` is the *only* concrete axis literal the model ever sees, and it
+appears twice with no counterexample:
+
+- Line 29: `Motions, with axis as a numeric vector like [0, 1, 0]:`
+- Line 40: `Every motion axis must be a numeric vector such as [0, 1, 0], never a string like x, y, or z.`
+
+The compact example payload (lines 52–68) uses a `pulse` motion, which has no
+`axis` field, so it adds no balancing example. With a single repeated exemplar
+and no contrast cases, an LLM under uncertainty defaults to the most available
+pattern — here, `[0, 1, 0]`. This is textbook few-shot anchoring.
+
+Note: `EXAMPLE_ANALYSIS` in `snap2sim/schema.py` is *not* injected into the
+prompt (the prompt is self-contained), so it does not directly steer the model.
+But it reflects the same lean: of its three parts that carry an axis, two are
+`[0, 1, 0]` (`ratchet_gear` rotate, `pawl` oscillate) and one is `[1, 0, 0]`
+(`selector_pin` translate). It is also the local sample-mode render, so the
+Y-lean is visible there too.
+
+### 2. Renderer hard default (`index.html`)
+
+`applyMotion`, line 1418:
+
+```js
+const axis = new THREE.Vector3(...(motion.axis || [0, 1, 0])).normalize();
+```
+
+If the model omits `axis` entirely (valid — `axis` is optional in the schema
+and coercion never injects one), the renderer animates about Y. So "model is
+biased to emit `[0, 1, 0]`" and "model omits axis" produce the *same* on-screen
+result: Y-axis motion. This makes the bias look even stronger than the model's
+raw output.
+
+### 3. Coercion fallback (`snap2sim/model_io.py`)
+
+- `_axis_vector` (lines 297–309) returns `None` when no usable axis is present;
+  `_coerce_part` only adds `axis` if truthy (lines 173–175). So omitted axes
+  stay omitted → renderer default (Y) applies.
+- `_generic_analysis` (line 232) hard-codes `"axis": [0, 1, 0]` for its rotor
+  part. Any fully-degraded response that falls back to the generic payload is
+  pure Y.
+
+## Why this is a real visual problem, not just cosmetics
+
+Geometry orientation and motion axis are decided **independently**, and they can
+disagree:
+
+- Geometry: `axisProfile` + `orientYAxisGeometry` / `orientZAxisGeometry`
+  (`index.html` lines 1319–1367) bake the primitive's long axis into the
+  geometry buffer using the **odd-one-out `size` dimension**. A cylinder with
+  `size [3, 0.5, 3]`... e.g. `size [2.0, 0.4, 0.4]` lays the shaft along world X.
+- Motion: `applyMotion` calls `mesh.rotateOnAxis(axis, …)` with the raw motion
+  axis (object space, and with no `baseRotation` that equals world space).
+
+So a shaft whose geometry was oriented along **X** but whose motion axis is the
+biased **`[0, 1, 0]`** will spin about Y — i.e. it sweeps end-over-end instead
+of rotating about its own length. The size-driven geometry inference added in
+`docs/reviews/scene-geometry-review.md` made geometry orientation smart, but
+motion axis was left to the model/default, so the two can visibly contradict.
+
+## Conclusion
+
+The prompt is a genuine contributor to the `[0, 1, 0]` lean, but fixing only the
+prompt will not fully resolve the on-screen behavior because the renderer
+default and generic fallback also resolve to Y. Address the prompt *and* make
+motion axis follow the geometry's inferred primitive axis when the model is
+silent or low-signal.
+
+## Next steps (for Codex to implement)
+
+1. **De-anchor the prompt** (`snap2sim/prompts.py`):
+   - In the motions section, show axis examples across all three world axes,
+     e.g. spin about a shaft's long axis `[1, 0, 0]` / `[0, 0, 1]` as well as
+     `[0, 1, 0]`, so no single axis is the lone exemplar.
+   - Add one sentence: the motion axis should match the part's real axis of
+     rotation/translation (usually the geometry's long/odd-one-out dimension),
+     not default to vertical.
+   - Optionally add a second `parts` exemplar in the compact shape that carries
+     an explicit non-`[0,1,0]` axis, to balance the `pulse` example.
+
+2. **Make the renderer default geometry-aware** (`index.html`):
+   - When `motion.axis` is absent, derive the default from the same
+     `axisProfile` result used to orient the geometry (map the inferred
+     `profile.axis` 0/1/2 to `[1,0,0]`/`[0,1,0]`/`[0,0,1]`) instead of the hard
+     `[0, 1, 0]`. This aligns spin with the part's long axis for free.
+   - Keep `[0, 1, 0]` only as the final fallback when no geometry/profile is
+     available.
+
+3. **Align the coercion fallback** (`snap2sim/model_io.py`):
+   - Consider deriving `_generic_analysis` rotor axis from its own geometry, or
+     at minimum document that the generic part is intentionally Y.
+   - Decide whether `_coerce_part` should inject a geometry-derived axis when the
+     model omits one (vs. leaving it to the renderer). Prefer leaving it to the
+     renderer so there is a single source of truth (option 2).
+
+4. **Verification after changes:**
+   - `EXAMPLE_ANALYSIS` and `docs/fixtures/mini-fan-analysis.json` render with
+     each part rotating about a sensible axis (shafts about their length).
+   - Schema/parser/coercion checks still pass; FastAPI `TestClient` smoke for
+     `/`, `/analyze_image`, `/generate_scene`.
+   - Re-run a representative Modal analysis and inspect the distribution of
+     emitted motion axes — confirm it is no longer almost entirely `[0, 1, 0]`.
+
+## Implementation status
+
+Completed locally on 2026-06-15:
+
+- Prompt examples now show X, Y, and Z axes and explicitly tell the model to
+  match motion axes to the real rotation or translation axis.
+- The deterministic renderer stores the geometry-inferred axis on each mesh
+  and uses it when `motion.axis` is omitted, keeping `[0, 1, 0]` only as the
+  final no-profile fallback.
+- `_generic_analysis` no longer hard-codes the rotor motion axis; its disk-like
+  geometry lets the renderer derive the Y axis from size.
+- Local schema/parser/coercion checks, FastAPI smoke checks, and Playwright
+  renderer probes passed.
+- Modal dev `run_analysis_endpoint_check` returned a rotating `dial` part with
+  `axis: [1, 0, 0]`, confirming the prompt no longer collapses the synthetic
+  check to `[0, 1, 0]`.
+- Stable Modal deployment completed after the prompt/renderer update, and an
+  unauthenticated deployed `runtime_probe` request returned `401 Unauthorized`.
+
+## Files referenced
+
+- `snap2sim/prompts.py` — `VISION_SYSTEM_PROMPT` (lines 29, 40), example payload.
+- `index.html` — `applyMotion` (line 1418), `axisProfile` (1319–1344),
+  `orientYAxisGeometry` / `orientZAxisGeometry` (1354–1367), `buildPartMesh`.
+- `snap2sim/model_io.py` — `_axis_vector` (297–309), `_coerce_part` (145–204),
+  `_generic_analysis` (~232).
+- `snap2sim/schema.py` — `EXAMPLE_ANALYSIS` axes, motion schema.

docs/reviews/scene-geometry-review.md

@@ -0,0 +1,212 @@
+# Scene Geometry Review: Rotation, Sizing, and Camera Y-Alignment
+
+Reviewer pass on the deterministic Three.js renderer in `index.html`, validated
+against `docs/fixtures/mini-fan-analysis.json` (a "mini fan": rotor cylinder,
+cage torus, base box), `snap2sim/schema.py`, and `snap2sim/prompts.py`.
+
+Scope: the three reported symptoms — **rotations are off**, **sizing is off**, and
+**the object is not aligned with the camera in Y** so the user cannot see all the
+detail. All three reproduce from the current code and have concrete root causes
+below. This document is for Codex to implement; it does not change any code.
+
+---
+
+## TL;DR
+
+All three symptoms originate in two places:
+
+1. `buildPartMesh()` (`index.html:1214`) builds every axial primitive with a
+   **hardcoded long axis** (mostly Y) and derives radius from `max(x, z)`,
+   ignoring how the model actually distributes the `[x, y, z]` extents. This
+   breaks both proportions (sizing) and apparent spin axis (rotation).
+2. `buildDeterministicScene()` (`index.html:890`) uses a **fixed camera** at
+   `(5.4, 3.9, 6.2)` looking at `(0, 0.1, 0)` with no bounding-box fit and no
+   recentering. Small models render as a dot; the assembly's vertical center is
+   wherever the model put it, not where the camera looks.
+
+The agreed direction (see **Decisions**): infer orientation from the `size`
+vector ("odd-one-out" axis), size the radial cross-section from the remaining
+pair, and apply any explicit `geometry.rotation` additively on top.
+
+---
+
+## Root Cause 1 — Rotations are off
+
+`buildPartMesh()` hardcodes the primitive's symmetry axis instead of deriving it
+from the `size` extents:
+
+- `index.html:1221` cylinder → `CylinderGeometry(r, r, y, ...)`: axis is **Y**,
+  height is always `y`.
+- `index.html:1224` cone → axis **Y**, height `y`.
+- `index.html:1228` capsule → axis **Y**, length `y`.
+- `index.html:1231` rod → built along Y then `rotateX(PI/2)` → axis **Z**
+  (inconsistent with cylinder).
+- `index.html:1236` torus → `rotateX(PI/2)` → ring lies flat in the XZ plane
+  (symmetry axis **Y**), always horizontal.
+- `index.html:1258` gear → extruded along Z, then `rotateX(PI/2)` → axis **Y**.
+- `index.html:1278` spring → built along **Y**.
+
+Because the geometry axis is fixed but the model places the real long/thin axis
+on whatever dimension is natural, the motion then *looks* wrong even though
+`applyMotion()` (`index.html:1303`) is correct.
+
+**Concrete failure (fan rotor, `docs/fixtures/mini-fan-analysis.json`):**
+`geometry.size = [0.12, 0.12, 0.35]`, `motion.axis = [0, 0, 1]`. The intent is a
+thin shaft whose long axis is **Z**, spinning about Z. The code builds a disk of
+radius `max(0.12, 0.35)/2 = 0.175` and height `0.12` oriented along **Y**, then
+spins it about world Z — so a fat short puck tumbles face-over instead of a hub
+spinning in place.
+
+**Concrete failure (fan cage):** `size = [0.55, 0.55, 0.04]` — the thin
+dimension is Z, so the guard ring should stand **upright facing the camera**
+(ring in the XY plane). The forced `rotateX(PI/2)` lays it **flat/horizontal**
+in the XZ plane instead.
+
+Note `applyMotion` uses `mesh.rotateOnAxis` in mesh-local space and the explicit
+model rotation is applied as `mesh.rotation.fromArray` (`index.html:962`). So if
+auto-orientation is baked into the *geometry* (via `geometry.rotate*`) rather than
+the mesh, motion axes stay in world space (the fan's `[0,0,1]` keeps spinning
+about world Z) and explicit `rotation` remains additive on the mesh. This is the
+clean separation to preserve.
+
+## Root Cause 2 — Sizing is off
+
+Two independent problems:
+
+**2a. Radius is taken from `max(x, z)` instead of the cross-section pair.**
+`index.html:1222` (`radius = Math.max(x, z) / 2`) and the analogous lines for
+cone/sphere/gear/torus. `size` is documented as full extents
+(`schema.py` / `prompts.py:18`), so a circular primitive has two ~equal extents
+(the diameter) and one different (the length). Using `max` picks the length when
+the long axis is X or Z, ballooning the radius and collapsing the length. Fan
+rotor: radius becomes `0.175` (should be `0.06`), height becomes `0.12` (should
+be `0.35`).
+
+**2b. No scene normalization or camera fit.** The camera, FOV, and OrbitControls
+distances are constants (`index.html:924`, `index.html:934-935`), but model
+scales vary by an order of magnitude:
+- `docs/fixtures/mini-fan-analysis.json` fan: extents `0.04`–`0.55`
+  (sub-unit).
+- `schema.py` `EXAMPLE_ANALYSIS`: extents `0.18`–`3.2` (unit-scale).
+
+At distance ~9 with a 42° FOV the view frames roughly 6–8 units. The fan
+(max extent ~0.55) renders as a speck dead center; a larger model can overflow
+or clip on the near plane. There is no `Box3`/bounding-sphere computation
+anywhere in `buildDeterministicScene()`.
+
+## Root Cause 3 — Object not aligned with the camera in Y
+
+The camera target is the constant `(0, 0.1, 0)` (`index.html:926`) and the grid
+sits at `y = 0` (`index.html:953`). Part positions come straight from the model
+(`index.html:961`) with arbitrary Y offsets and no recentering. The assembly's
+vertical center is therefore wherever the model happened to place it, not where
+the camera looks — so the object floats high or low and detail is cut off or
+off-center. The fix for this is the same bounding-box work as 2b: recenter the
+assembly (especially in Y) onto the camera target, then fit the distance.
+
+---
+
+## Recommended fixes / next steps (for Codex)
+
+Order matters; 1–3 are the substantive changes.
+
+### 1. Derive primitive orientation and radius from the `size` vector
+Rewrite `buildPartMesh()` (`index.html:1214`) for the axial/disk shapes:
+
+- Compute the **odd-one-out axis**: the size dimension that differs most from the
+  other two. For cylinder/cone/capsule/rod/spring this is the elongated axis;
+  for torus/gear it is the thin (normal) axis. Same selector, both cases:
+  - `[0.12, 0.12, 0.35]` → pair `(x, y)=0.12`, odd `z` → **axis Z**, diameter 0.12.
+  - `[3.2, 0.55, 3.2]`  → pair `(x, z)=3.2`,  odd `y` → **axis Y**, diameter 3.2.
+  - `[0.55, 0.55, 0.04]` (torus) → odd `z` → ring stands in XY, faces camera.
+- Cross-section **radius = mean of the two non-axis extents / 2** (not `max`).
+- Build each primitive in its native Three.js orientation (axis = Y) with
+  `height/length = extent along the detected axis`, then rotate the
+  **BufferGeometry** so its Y maps onto the detected axis (skip when axis is Y).
+  Keep using `geometry.rotate*` so motion axes stay in world space.
+- Fallback when all three extents are distinct (no clear pair): for cylinder-like
+  shapes use the **max** extent as the axis; for torus/gear use the **min**
+  extent. Otherwise default to Y (current behavior). Document the fallback.
+- Remove the now-redundant fixed `rotateX(PI/2)` on rod (`index.html:1233`),
+  torus (`index.html:1240`), and gear (`index.html:1274`) — orientation comes
+  from the detected axis instead.
+- Leave the existing `mesh.rotation.fromArray(geometry.rotation)`
+  (`index.html:962`) untouched: explicit model rotation now layers additively on
+  top of the auto-orientation. Confirm `sphere` (no axis) and `box` (exact
+  extents) are unaffected.
+
+### 2. Recenter the assembly and fit the camera to its bounding box
+In `buildDeterministicScene()` (`index.html:890`), after the meshes are created
+and **before** the reveal animation shrinks them:
+
+- Put the part meshes in a `THREE.Group` (or compute over the mesh list) and
+  build a `THREE.Box3`. Measure at **full scale** — currently `mesh.scale` is set
+  to `0.001` for the reveal at `index.html:972`, so either measure before that
+  line or derive the box from geometry bounding boxes. Do not measure the grid.
+- Recenter so the assembly center sits at the origin (translate group by
+  `-center`, or store the offset). This is what aligns the object in **Y** with
+  the camera target — the reported issue 3.
+- Compute the bounding **sphere** radius and set the camera distance from FOV and
+  aspect: `distance = (radius / sin(fov/2)) * margin`, taking the max of the
+  vertical and horizontal (aspect-corrected) fit so wide models do not clip.
+  Keep the existing pleasing 3/4 viewing direction — normalize
+  `(5.4, 3.9, 6.2)` and scale it by the computed distance.
+- Set `controls.target` to the recentered center (origin) and derive
+  `minDistance`/`maxDistance` from `radius` (e.g. `radius*0.6` .. `radius*6`)
+  instead of the hardcoded `2.4`/`12` (`index.html:934-935`). Recompute
+  `defaultCameraPosition`/`defaultTarget` so **Reset view** (`index.html:982`)
+  still lands on the fitted framing.
+- Move the grid (`index.html:953`) to the bottom of the recentered box
+  (`y = box.min.y`) so it reads as a ground plane instead of bisecting the part.
+- Re-run the fit inside `resize()` (`index.html:996`) so aspect changes (mobile,
+  window resize) keep the object framed.
+
+### 3. Verify motion still reads correctly after re-orientation
+With orientation in geometry and motion axes in world space, confirm against
+`docs/fixtures/mini-fan-analysis.json`:
+- Rotor spins about Z **in place** as a slim hub (not a tumbling puck).
+- Cage stands upright facing the camera and stays static.
+- Base sits beneath, assembly vertically centered in the viewport.
+Spot-check `schema.py` `EXAMPLE_ANALYSIS` (gear about Y, oscillating pawl,
+translating selector pin, pulsing spring, flat retaining ring) for regressions.
+
+### 4. Optional / follow-up
+- The prompt (`prompts.py:18`) and schema example mix conventions (the example
+  gives equal `x,z` **plus** an explicit `rotation`; the fan gives neither and
+  relies on the long axis being in `size`). After the renderer auto-orients,
+  tighten the prompt so the model is told the renderer infers axis from `size`
+  and that `rotation` is only a fine-tuning offset — reduces conflicting/double
+  rotations from the model.
+- Consider clamping or warning when a part's extents are wildly out of range
+  relative to the rest of the assembly, so one bad number can't blow up the fit.
+
+---
+
+## Decisions (confirmed with the user)
+
+- **Orientation:** auto-orient axial/disk primitives from the `size` vector using
+  the odd-one-out axis; radius from the remaining pair; apply explicit
+  `geometry.rotation` additively on top. (Not the "trust explicit rotation only"
+  approach — the fan output carries no rotation and must still render correctly.)
+
+## Open considerations (flag if hit during implementation)
+
+- True ambiguous case (all three extents distinct, e.g. an elliptical cross
+  section): the spec uses the max/min fallback above. Three.js cylinders are
+  circular, so a non-circular cross section can only approximate — note it rather
+  than over-engineer.
+- Whether to normalize the whole scene to a fixed target size instead of fitting
+  the camera. Camera-fit (recommended above) preserves real relative scale
+  between parts; global normalization would flatten it. Implement camera-fit
+  unless a reason to do otherwise surfaces.
+
+## Verification checklist
+
+- `python -c "import snap2sim.schema, snap2sim.prompts"` and existing schema/parser
+  checks still pass (no Python contract change expected).
+- FastAPI `TestClient` for `/`, `/analyze_image`, `/generate_scene` unchanged.
+- Browser: load `docs/fixtures/mini-fan-analysis.json` through the deterministic path and confirm
+  fan rotor proportions/axis, upright cage, vertical centering, and a sensible
+  frame at both sub-unit (fan) and unit-scale (`EXAMPLE_ANALYSIS`) inputs.
+- Resize / mobile: object stays centered and framed; OrbitControls still orbit,
+  pan, zoom; **Reset view** returns to the fitted framing.

docs/reviews/security-hardening.md

@@ -0,0 +1,290 @@
+# Security Hardening Review
+
+Review date: 2026-06-14. Reviewer: Claude (Opus 4.8), for OpenAI Codex to implement.
+
+This review answers three questions:
+
+1. Are the endpoints secure?
+2. Is the UI/UX good?
+3. Should we prioritize Three.js or A-Frame for animation rendering?
+
+Two product decisions were confirmed with the owner and shape the priorities below:
+
+- **The Space is going public soon.** Findings that are only mitigated by the
+  Space being private are therefore treated as blockers, not nice-to-haves.
+- **Screen-only viewing; no VR/AR goal.** WebXR is not required, which removes
+  A-Frame's main structural advantage.
+
+File references use `path:line` from the state of the repo at review time.
+
+---
+
+## 1. Endpoint Security
+
+### Architecture summary
+
+- `app.py` is the public Hugging Face Space (`gradio.Server`). It serves
+  `index.html` at `/` and exposes `POST /analyze_image` and
+  `POST /generate_scene`. The browser calls these **same-origin**, and the
+  server attaches the Modal bearer token when it forwards to Modal. This split
+  (token stays server-side) is correct and matches `SECURITY.md`.
+- `modal_app.py` exposes the GPU/inference web endpoints, each guarded by a
+  bearer token via `require_authorization`.
+
+The Modal layer is in good shape. The Space layer is the exposure.
+
+### HIGH — The Space's own `/analyze_image` and `/generate_scene` are unauthenticated (`app.py:64`, `app.py:74`)
+
+These endpoints have no auth of their own. Today they are gated only by the
+Space being private. **Once the Space is public, anyone on the internet can POST
+to them.**
+
+- With `INFERENCE_BACKEND=local` (current default), they return placeholder data
+  — low impact but a free compute/bandwidth sink (base64 decode + PIL decode +
+  scene build per request).
+- With `INFERENCE_BACKEND=modal`, every public request is proxied to Modal
+  **using the server's own bearer token**, turning the Space into an open proxy
+  that spends GPU credits on behalf of any anonymous caller. The Modal bearer
+  token protects Modal from direct callers, but the Space is a trusted caller,
+  so the token does not help here. This directly contradicts the stated intent
+  in `SECURITY.md` that the token is "the real protection against
+  credit-spending spam."
+
+**Recommendation (before going public):**
+
+- Add abuse controls at the Space layer that do not require leaking a secret to
+  the browser. Options, roughly in order of preference:
+  1. **Server-side rate limiting / quota** per client IP and a global ceiling
+     (e.g. `slowapi`/`limits`, or a small in-process token bucket). This is the
+     most important mitigation since the Space is intentionally token-free on
+     the client side.
+  2. A short-lived, server-issued session/CSRF-style token handed to the page on
+     `GET /` and required on the POST endpoints, to stop trivial scripted abuse
+     (not a strong control, but raises the bar).
+  3. Hard caps: max upload size, max requests/min, and a circuit breaker that
+     falls back to `local` placeholder mode if a Modal spend threshold is hit.
+- Consider HF Space-level protections too (HF supports gating), but do not rely
+  on them as the only layer once public.
+
+### HIGH — Untrusted scene HTML is injected via `innerHTML` (`index.html:545`)
+
+`renderAframe()` does `viewport.innerHTML = sceneHtml;` where `sceneHtml` comes
+from `/generate_scene`. In the deterministic path the HTML is built server-side
+with `html.escape` (`snap2sim/aframe_scene.py:14-16`, safe). But the
+model-generation path (`generate_scene_llamacpp` in `modal_app.py:462`) returns
+**raw model output**, extracted by `parse_scene_response`
+(`snap2sim/model_io.py:49`) which does *no sanitization* — it slices everything
+between `<a-scene>` and `</a-scene>` verbatim.
+
+Because the scene is derived from a **user-uploaded image**, an attacker can
+prompt-inject the vision/scene model (text in the photo, adversarial content)
+into emitting markup such as `<a-entity onloaded="...">` or
+`<img src=x onerror=...>`. `innerHTML` will not execute injected `<script>`
+tags, but it *does* run inline event-handler attributes and A-Frame can execute
+component JS — so this is a realistic stored/reflected XSS vector that becomes
+internet-reachable when the Space is public.
+
+The validation in `validate_analysis` protects the *JSON analysis* path but does
+nothing for the free-form HTML scene path.
+
+**Recommendation:** Do not inject free-form model HTML into the DOM. See §3 —
+the cleanest fix is to make scene rendering deterministic from the validated
+JSON (which is already escaped/validated) and stop returning model-authored
+HTML. If any model-authored HTML is ever rendered, sanitize it with an
+allowlist (e.g. DOMPurify with an A-Frame-aware tag/attribute allowlist) before
+`innerHTML`, and strip all `on*` attributes.
+
+### MEDIUM — No upload size limit or decompression-bomb hardening (`app.py:88`, `modal_app.py:327`)
+
+`_decode_image` and `write_payload_image` do `base64.b64decode(...)` then
+`Image.open(BytesIO(...))` with no cap on the base64 string length or decoded
+pixel count. A large or crafted image (decompression bomb) can exhaust memory on
+`cpu-basic`. PIL's default `DecompressionBombWarning` only warns; it does not
+block at typical sizes.
+
+**Recommendation:**
+
+- Reject requests whose base64 body exceeds a sane limit (e.g. ~8–12 MB) before
+  decoding.
+- Set `Image.MAX_IMAGE_PIXELS` to an explicit ceiling and catch
+  `Image.DecompressionBombError`.
+- Wrap decode failures and return a clean `400` instead of a 500/stack trace.
+
+### MEDIUM — Fixed temp file paths cause cross-request collisions (`modal_app.py:199`, `modal_app.py:342`)
+
+Both the smoke test and `write_payload_image` write to fixed paths
+(`/tmp/snap2sim-request-image.jpg`). Concurrent requests on the same container
+overwrite each other's input image, so one user could be analyzed against
+another user's photo. This is both a correctness and a privacy concern.
+
+**Recommendation:** Use `tempfile.NamedTemporaryFile`/`mkstemp` (unique per
+request) and clean up in a `finally`.
+
+### LOW — Third-party scripts loaded without Subresource Integrity (`index.html:7-13`)
+
+A-Frame (`aframe.io`), the Gradio client (`jsdelivr`), and fonts
+(`bunny.net`) are loaded from CDNs with no `integrity`/SRI hashes. A CDN
+compromise would run arbitrary JS in the (soon public) page.
+
+**Recommendation:** Pin versions and add SRI hashes where the CDN supports it.
+Note: if A-Frame is dropped (see §3) and Three.js is bundled/self-hosted, this
+surface shrinks substantially.
+
+### LOW — Unused third-party dependency loaded (`index.html:10-13`)
+
+The Gradio JS client is imported into `window.snap2simGradioClient` but never
+used; all calls go through a plain `fetch` (`postJson`, `index.html:765`).
+Remove the import to cut an unnecessary CDN dependency and load.
+
+### Positives (keep these)
+
+- Modal bearer check uses constant-time comparison
+  (`token_secrets.compare_digest`, `modal_app.py:113`) and returns `503` when
+  the token is unconfigured, `401` on mismatch (`modal_app.py:105-115`).
+  Unauthenticated `401` was verified per AGENTS.md.
+- Token never reaches the browser; server-side attaches it
+  (`snap2sim/backend.py:62-68`). Matches `SECURITY.md` guidance.
+- The deterministic scene builders escape text with `html.escape`
+  (`snap2sim/aframe_scene.py:14-16`) and the analysis readout uses `textContent`
+  rather than `innerHTML` (`index.html:513-536`) — no XSS on that path.
+- GitHub→HF workflow uses least-privilege `permissions: contents: read` and
+  keeps `HF_TOKEN` in secrets (`.github/workflows/sync_to_hf.yml:19-21`).
+- Schema validation (`snap2sim/schema.py:176`) runs before scene generation.
+
+---
+
+## 2. UI/UX
+
+The visual direction is strong and cohesive: a "technical cutaway / field
+manual" aesthetic (amber `#E8A33D` + cyan `#5FD4D0` on dark, blueprint grid,
+Chakra Petch / Fira Code). The two-pane layout (viewport + readout) is clear and
+the loading choreography (progress bar, scan-line reveal, staggered mesh
+reveal, cold-start "WAKING THE WORKSHOP" message after 6.5 s) is a genuinely
+nice touch for HF cold starts. Drag-and-drop plus a Load button, and a
+play/pause control, cover the core interactions. The fallback chain
+(A-Frame → deterministic Three.js → "3D runtime unavailable") is thoughtful.
+
+### Issues, roughly by impact
+
+**Accessibility (MEDIUM — matters more once public):**
+
+- Status messages (`index.html:392`) are not announced to screen readers. Add
+  `aria-live="polite"` (and `role="status"`) so analysis progress/errors are
+  read out.
+- `#viewport` injected 3D content has no text alternative. Provide an
+  `aria-label`/visually-hidden description, or rely on the readout panel as the
+  accessible representation and mark the viewport `aria-hidden`.
+- Low-contrast text: `--text-muted #6B7280` on the dark panel is below WCAG AA
+  for body text (`trigger`, raw JSON, drop-zone hint). Nudge it lighter.
+- The file input is triggered via a `<label>` drop zone (`index.html:382`); make
+  sure keyboard focus + Enter works to open the picker, and the Load button is
+  already focusable (good).
+
+**Functional gaps:**
+
+- **No preview of the uploaded photo.** Users lose their reference image once
+  the cutaway renders. Show a thumbnail of the source photo in the panel — it
+  also reinforces the "this came from *my* object" story for a demo.
+- **`playButton` initial state is confusing** (`index.html:379`): it reads
+  "Pause" while disabled, before any scene exists. Start as disabled "Play" or
+  hide until a scene is ready.
+- **Error UX is thin:** errors render as uppercased status text only
+  (`index.html:495`). Add a visible retry affordance and keep the drop zone
+  reachable so the user can try another photo without hunting for the Load
+  button.
+- **No client-side file validation:** `accept="image/*"` only. Reject
+  non-images and oversized files before base64 inflation (~33% size increase)
+  and surface a friendly message. (Pairs with the server-side size cap in §1.)
+- **Mobile:** the layout has a breakpoint at 860 px (good), but A-Frame
+  `look-controls` can capture touch/scroll. If Three.js becomes the primary
+  renderer (see §3), use OrbitControls tuned for touch and ensure the page still
+  scrolls. Also consider `capture="environment"` to offer "take a photo" on
+  mobile.
+- **No confidence visualization:** confidence is shown as a number
+  (`index.html:516`); a small bar/gauge would read faster and fit the
+  instrument aesthetic.
+- **First-run onboarding** is just "Drop component photo." A one-line example
+  ("try a lock, a gear, a ratchet…") lowers the cold-start barrier for judges.
+
+**Verdict:** UI/UX is above-average for a hackathon and the aesthetic is a real
+asset. The gaps are accessibility, an uploaded-image preview, and error/retry
+polish — none are large, and they raise the demo from "looks great" to "feels
+finished."
+
+---
+
+## 3. Three.js vs A-Frame for Rendering
+
+**Recommendation: consolidate on Three.js as the primary (and only) renderer,
+driven deterministically from the validated JSON analysis. Drop the A-Frame
+dependency and stop returning model-authored scene HTML.**
+
+### Reasoning
+
+1. **No VR/AR goal (confirmed).** A-Frame's defining advantage is declarative
+   WebXR. Screen-only viewing removes the main reason to carry it. Without VR,
+   A-Frame is mostly a ~1.2 MB declarative wrapper over Three.js.
+
+2. **The Three.js path is already the more capable implementation.** The
+   "fallback" in `index.html:565-755` has OrbitControls, DOM-projected part
+   labels, staggered reveal, gear extrusion, fog/lighting, and motion handling.
+   It is richer than the A-Frame output (`snap2sim/aframe_scene.py`). You'd be
+   promoting your best renderer, not rewriting one.
+
+3. **True "cutaway" cross-sections need clipping planes.** The product is an
+   *annotated technical cutaway*. Three.js exposes
+   `renderer.localClippingEnabled` + `material.clippingPlanes` natively, which is
+   the clean way to slice a housing and reveal internals. A-Frame has no
+   first-class clipping-plane support. If "cutaway" is to be more than parts
+   floating in space, Three.js is required anyway.
+
+4. **It removes the §1 HIGH XSS vector.** Rendering deterministically from
+   validated JSON means no `innerHTML` of untrusted model HTML. The model
+   already produces the structured JSON (`snap2sim/schema.py`), which is
+   validated and safe; let a deterministic Three.js builder turn that JSON into
+   geometry. This is both safer and more *reliable* than asking an LLM to emit
+   well-formed scene markup.
+
+5. **Smaller, self-hostable footprint.** Three.js can be pinned/bundled and
+   served same-origin, shrinking the CDN/SRI surface from §1.
+
+### What this means concretely for implementation
+
+- **Keep the model's job as the JSON `analysis` contract** (it already is,
+  `snap2sim/schema.py`). The model should *not* author HTML/JS scenes.
+- **Make `generate_scene` deterministic** from that JSON. The browser already
+  has `buildDeterministicScene()` — promote it from fallback to the main path.
+  You can drop the server returning scene HTML entirely, or keep the server
+  returning the validated analysis and let the browser build the scene.
+- **Remove A-Frame** (`index.html:9`, the `<a-scene>` injection in
+  `renderAframe`, and the A-Frame branch of `generate_scene_llamacpp`) once the
+  Three.js path is the default. Delete `snap2sim/aframe_scene.py` and the
+  A-Frame prompt template after migration, or keep them only if you want a
+  server-rendered static preview.
+- **If you keep any model-authored HTML path**, it must be sanitized
+  (DOMPurify, strip `on*`) per §1.
+
+This also simplifies the mental model: one renderer, one safe data contract,
+no dual A-Frame/Three.js maintenance.
+
+---
+
+## Suggested Implementation Order (for Codex)
+
+Blockers before the Space goes public:
+
+1. Add server-side rate limiting / quota + max upload size to `app.py`
+   endpoints (§1 HIGH).
+2. Eliminate the untrusted-HTML `innerHTML` path: move to deterministic Three.js
+   rendering from validated JSON, or sanitize (§1 HIGH + §3).
+3. Add decompression-bomb guards and unique temp files (§1 MEDIUM).
+
+Then:
+
+4. Consolidate rendering on Three.js; remove A-Frame and the dead Gradio client
+   import; add SRI/self-hosting (§3, §1 LOW).
+5. UI/UX polish: uploaded-image preview, `aria-live` status, contrast fix,
+   error/retry affordance, play-button initial state (§2).
+
+Out of scope / leave as-is: Modal bearer auth (already correct), the
+GitHub→HF sync workflow, the schema contract.

index.html

@@ -1268,37 +1268,45 @@
       const y = Math.max(0.05, Number(size[1]) || 1);
       const z = Math.max(0.05, Number(size[2]) || 1);
       let geometry;
+      let inferredMotionAxis = [0, 1, 0];
       if (geometryData.shape === "cylinder") {
         const profile = axisProfile([x, y, z], "max");
+        inferredMotionAxis = axisVector(profile.axis);
         geometry = new THREE.CylinderGeometry(profile.radius, profile.radius, profile.length, 48);
         orientYAxisGeometry(geometry, profile.axis);
       } else if (geometryData.shape === "cone") {
         const profile = axisProfile([x, y, z], "max");
+        inferredMotionAxis = axisVector(profile.axis);
         geometry = new THREE.ConeGeometry(profile.radius, profile.length, 48);
         orientYAxisGeometry(geometry, profile.axis);
       } else if (geometryData.shape === "sphere") {
         geometry = new THREE.SphereGeometry(Math.max(x, y, z) / 2, 36, 18);
       } else if (geometryData.shape === "capsule") {
         const profile = axisProfile([x, y, z], "max");
+        inferredMotionAxis = axisVector(profile.axis);
         const radius = Math.min(profile.radius, profile.length / 2);
         geometry = new THREE.CapsuleGeometry(radius, Math.max(0.05, profile.length - radius * 2), 8, 24);
         orientYAxisGeometry(geometry, profile.axis);
       } else if (geometryData.shape === "rod") {
         const profile = axisProfile([x, y, z], "max");
+        inferredMotionAxis = axisVector(profile.axis);
         geometry = new THREE.CylinderGeometry(profile.radius, profile.radius, profile.length, 24);
         orientYAxisGeometry(geometry, profile.axis);
       } else if (geometryData.shape === "gear") {
         const profile = axisProfile([x, y, z], "min");
+        inferredMotionAxis = axisVector(profile.axis);
         geometry = gearGeometry(profile.radius, profile.length, geometryData.teeth || 18);
         orientZAxisGeometry(geometry, profile.axis);
       } else if (geometryData.shape === "torus") {
         const profile = axisProfile([x, y, z], "min");
+        inferredMotionAxis = axisVector(profile.axis);
         const outerRadius = profile.radius;
         const tube = Math.min(profile.length / 2, outerRadius * 0.36);
         geometry = new THREE.TorusGeometry(Math.max(0.05, outerRadius - tube), Math.max(0.025, tube), 16, 64);
         orientZAxisGeometry(geometry, profile.axis);
       } else if (geometryData.shape === "spring") {
         const profile = axisProfile([x, y, z], "max");
+        inferredMotionAxis = axisVector(profile.axis);
         geometry = springGeometry(profile.radius, profile.length, geometryData.coils || 5, geometryData.wire);
         orientYAxisGeometry(geometry, profile.axis);
       } else {
@@ -1313,7 +1321,9 @@
         emissive: color,
         emissiveIntensity: 0.04
       });
-      return new THREE.Mesh(geometry, material);
+      const mesh = new THREE.Mesh(geometry, material);
+      mesh.userData.inferredMotionAxis = inferredMotionAxis;
+      return mesh;
     }
 
     function axisProfile(extents, fallback) {
@@ -1343,6 +1353,12 @@
       };
     }
 
+    function axisVector(axis) {
+      if (axis === 0) return [1, 0, 0];
+      if (axis === 2) return [0, 0, 1];
+      return [0, 1, 0];
+    }
+
     function dimensionsAreClose(left, right) {
       return relativeDifference(left, right) <= 0.2;
     }
@@ -1415,7 +1431,8 @@
       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();
+      const axisValues = motion.axis || mesh.userData.inferredMotionAxis || [0, 1, 0];
+      const axis = new THREE.Vector3(...axisValues).normalize();
       mesh.position.copy(mesh.userData.basePosition);
       mesh.rotation.copy(mesh.userData.baseRotation);
       if (motion.type === "rotate") {

snap2sim/model_io.py

@@ -229,7 +229,7 @@ def _generic_analysis(component: str) -> dict[str, Any]:
                 "name": "central rotor",
                 "role": "transfers motion through the assembly",
                 "geometry": {"shape": "cylinder", "size": [0.9, 0.35, 0.9], "position": [0, 0.18, 0]},
-                "motion": {"type": "rotate", "axis": [0, 1, 0], "speed": 0.55},
+                "motion": {"type": "rotate", "speed": 0.55},
             },
             {
                 "id": "guide",

snap2sim/prompts.py

@@ -26,7 +26,8 @@ Shapes, with size always [x, y, z] extents:
 - torus: o-rings, snap rings, seals, washers, single coils
 - spring: helical springs and coils; set coils when useful
 
-Motions, with axis as a numeric vector like [0, 1, 0]:
+Motions, with axis as a numeric vector when direction matters. Use [1, 0, 0],
+[0, 1, 0], or [0, 0, 1] for world X/Y/Z directions:
 - static: fixed structure or housing
 - rotate: continuous spin; use speed
 - oscillate: sinusoidal twist; use amplitude and speed
@@ -37,7 +38,10 @@ Motions, with axis as a numeric vector like [0, 1, 0]:
 
 Every geometry must use size: [x, y, z] and position: [x, y, z]. Do not use
 radius, height, length, width, or depth fields. Every motion axis must be a
-numeric vector such as [0, 1, 0], never a string like x, y, or z.
+numeric vector such as [1, 0, 0], [0, 1, 0], or [0, 0, 1], never a string like
+x, y, or z. Match the motion axis to the real axis of rotation or translation;
+for shafts, pins, disks, and springs this is usually the geometry's
+odd-one-out size dimension, not automatically vertical.
 For axial or disk-like shapes, express the main axis or disk normal through the
 size vector: one dimension should differ from the other two. The renderer uses
 that odd-one-out dimension for the primitive axis and treats rotation as a
@@ -63,6 +67,13 @@ Use this compact shape:
       "geometry": {"shape": "spring", "size": [0.4, 1.2, 0.4], "position": [0, 0, 0], "coils": 6},
       "motion": {"type": "pulse", "speed": 2, "amplitude": 0.08},
       "annotation": {"point": [0.5, 0.5], "label": "visible label", "note": "short visible clue"}
+    },
+    {
+      "id": "shaft",
+      "name": "drive shaft",
+      "role": "rotates along its length",
+      "geometry": {"shape": "cylinder", "size": [1.2, 0.25, 0.25], "position": [0, 0.45, 0]},
+      "motion": {"type": "rotate", "axis": [1, 0, 0], "speed": 1.4}
     }
   ]
 }