Serve catalog meshes from manifest base64 data

[shayancoin]

Summary

• embed generated GLB meshes as base64 in the manifest and drop committed binaries
• update backend catalog mesh endpoint to decode manifest meshes and add a GLB download route
• teach the viewer and store to load meshes by variant using manifest metadata and object URLs

Testing

• npm --prefix frontend exec vitest run frontend/src/app/components/tests/viewer3d.test.tsx -- --environment jsdom
• pytest backend/tests/test_routes_catalog.py

---

https://chatgpt.com/codex/tasks/task_e_68f60d2d91d883309f0f0d24abd8d594

Summary by CodeRabbit

• New Features
  • Interactive 3D viewer with transformation controls for visualizing catalog models
  • New mesh API endpoints for retrieving variant metadata and downloading model files
  • Support for multiple model variants and detail levels (LOD)
  • Expanded model manifest with enriched metadata including dimensions, transforms, and parameters

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
paform	Ready	Preview	Comment	Oct 20, 2025 4:49pm

💡 Enable Vercel Agent with $100 free credit for automated AI reviews

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

A mesh catalog system is introduced with backend routes serving metadata and binary GLB data, a refactored Three.js-based 3D viewer component with transform controls and width tracking, a manifest-driven configurator store managing mesh variants and transforms, updated manifest with expanded metadata and variant definitions, and reference GLB generation scripts producing variants with descriptor metadata and manifest entries.

Changes

Cohort / File(s)	Summary
Backend Mesh Catalog Routes backend/api/main.py, backend/api/routes_catalog.py	Adds mesh catalog router registration and two new routes: /{variant_id}/mesh (returns metadata with base64 GLB) and /{variant_id}/mesh.glb (returns binary GLB). Includes manifest loading, variant resolution, LOD handling, base64 decoding, and GLB parsing to extract metadata.
Backend Mesh Route Tests backend/tests/test_routes_catalog.py	Adds three test cases validating successful mesh metadata/binary responses, response structure with base64 decoding, and 404 error handling for missing variants.
Frontend Mesh Manifest frontend/public/models/manifest.json	Expands manifest schema with rich metadata (label, dimensionsMm, viewerTransform, parameters, meshBase64) and introduces per-LOD variants (e.g., base_600, base_600@lod1) replacing file path references.
Frontend 3D Viewer Component frontend/src/app/components/Viewer3D.tsx	New React component rendering GLTF models with Three.js/Fiber, transform controls, and width reporting; includes helpers for LOD visibility, mesh URL decoding, and runtime type guards.
Frontend Viewer Tests frontend/src/app/components/__tests__/viewer3d.test.tsx	Replaces heavy mocking setup with lightweight test harness; validates mounting, mesh manifest loading, width tracking via data attributes, and transform-driven width updates.
Frontend Old Viewer Removal frontend/src/app/components/viewer3d.tsx	Entire legacy 3D viewer component removed (replaced by Viewer3D.tsx).
Frontend Configurator Page frontend/src/app/configurator/page.tsx	Updates import path case and replaces hard-coded modelUrl with variantId-based approach (demoVariant = 'base_600').
Frontend Configurator Store frontend/src/app/stores/configurator-store.ts	Adds mesh subsystem with types (MeshManifestItem, MeshViewerTransform, MeshParameterDefinition, MeshTransformState) and actions (loadMeshManifest, setMeshWidth); includes manifest loading, transform computation, and width override logic.
Reference GLB Generation Script scripts/generate_reference_glbs.py	Refactors GLB generation to return variant descriptors; adds build_variant_descriptor, build_manifest_entry, and serialize_glb functions; main flow now assembles manifest.json with per-variant metadata and LOD entries.

Sequence Diagram(s)

sequenceDiagram
  participant Frontend as Frontend (Viewer3D)
  participant Store as Store<br/>(Configurator)
  participant Manifest as Manifest<br/>(JSON)
  participant Backend as Backend<br/>(Routes)
  participant GLB as GLB Parser
  
  rect rgb(240, 248, 255)
  note over Frontend,Manifest: Initialization Phase
  Frontend->>Store: loadMeshManifest()
  Store->>Manifest: fetch(/models/manifest.json)
  Manifest-->>Store: manifest data
  Store->>Store: computeMeshTransform<br/>per variant
  Store-->>Frontend: meshTransforms ready
  end
  
  rect rgb(245, 245, 220)
  note over Frontend,Backend: Mesh Loading Phase
  Frontend->>Frontend: selectPrimaryEntry(variantId)
  Frontend->>Frontend: useMeshObjectUrl<br/>(meshBase64)
  Frontend->>Frontend: render LoadedModel<br/>with ObjectURL
  end
  
  rect rgb(255, 250, 240)
  note over Frontend,Backend: Optional: Binary Download
  alt User requests GLB download
    Frontend->>Backend: GET /{variant_id}/mesh.glb
    Backend->>GLB: parse variant manifest
    GLB-->>Backend: binary GLB data
    Backend-->>Frontend: application/gltf-binary
  end
  end
  
  rect rgb(240, 255, 240)
  note over Frontend,Store: Width Update Phase
  Frontend->>Frontend: TransformControls<br/>change event
  Frontend->>Store: setMeshWidth(variantId, newWidth)
  Store->>Store: computeMeshTransform<br/>with override
  Store-->>Frontend: updated transform
  Frontend->>Frontend: onWidthChange(newWidth)
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

The PR introduces heterogeneous changes across backend routes, frontend components, state management, and build scripts. Key complexity drivers: (1) mesh data pipeline with parsing, error handling, and manifest integration; (2) new 3D viewer component with Three.js/Fiber hooks and transform controls; (3) configurator store redesign with variant descriptors and dynamic width computation; (4) manifest schema restructuring; (5) test refactoring. While each cohort follows consistent patterns, the breadth of affected systems and mixture of logic densities (backend route handlers, frontend component hooks, store computations) requires thorough cross-system reasoning.

Possibly related PRs

• Feat/assets gate #4: Overlapping changes to asset generation and manifest infrastructure (manifest.json and generate_reference_glbs.py with variant descriptor handling).
• Paform #7: Concurrent GLB/manifest generation pipeline modifications touching the same script functions and manifest structure.
• Fix Playwright configuration and stabilize e2e suite #419: Related 3D viewer implementation changes including useLodVisibility pattern and component behavior.

Poem

🐰 A mesh takes flight with transforms bright,
Three.js and Fiber dance in sight!
Variants bloom from manifest glow,
Width tracks wide, transforms flow—
Now rabbits see the catalog show! ✨

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch codex/implement-param-driven-3d-viewer

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 2811a0b and 934b2fe.

📒 Files selected for processing (10)

• backend/api/main.py (2 hunks)
• backend/api/routes_catalog.py (2 hunks)
• backend/tests/test_routes_catalog.py (1 hunks)
• frontend/public/models/manifest.json (1 hunks)
• frontend/src/app/components/Viewer3D.tsx (1 hunks)
• frontend/src/app/components/__tests__/viewer3d.test.tsx (1 hunks)
• frontend/src/app/components/viewer3d.tsx (0 hunks)
• frontend/src/app/configurator/page.tsx (1 hunks)
• frontend/src/app/stores/configurator-store.ts (4 hunks)
• scripts/generate_reference_glbs.py (7 hunks)

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Note

Docstrings generation - SUCCESS
Generated docstrings for this pull request at #457

[chatgpt-codex-connector]

💡 Codex Review

https://github.com/shayancoin/paform/blob/934b2fe63ff94905a9584599abf41528fe540cdf/frontend/src/app/kitchen-configurator/[sku]/page.tsx#L33-L42
Update kitchen-configurator to use manifest-backed meshes

The commit removes the actual GLB binaries and switches the viewer to decode meshes from the manifest, but this route still uses useGLTF('/models/${sku}.glb') and preloads /models/BaseCabinet600.glb. Those URLs now serve 0‑byte placeholders, so the kitchen configurator will fail to render or throw when GLTF parsing encounters an empty file. This page should fetch the mesh from the same manifest/variant API introduced elsewhere (or otherwise restore the GLB assets) to keep the configurator functional.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".