meshvault 0.1.0__tar.gz

meshvault-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Laurent-Philippe Albou (contact@abstractcore.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

meshvault-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: meshvault
+Version: 0.1.0
+Summary: A professional 3D asset browser for rapid browsing, previewing, and managing OBJ/FBX files
+License: MIT
+License-File: LICENSE
+Keywords: 3d,asset-browser,obj,fbx,three.js,viewer,meshvault
+Author: Laurent-Philippe Albou
+Author-email: contact@abstractcore.ai
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Classifier: Topic :: Multimedia :: Graphics :: Viewers
+Requires-Dist: aiofiles (>=24.1.0,<25.0.0)
+Requires-Dist: fastapi (>=0.115.0,<0.116.0)
+Requires-Dist: python-multipart (>=0.0.9,<0.0.10)
+Requires-Dist: rarfile (>=4.2,<5.0)
+Requires-Dist: trimesh (>=4.4.0,<5.0.0)
+Requires-Dist: uvicorn[standard] (>=0.30.0,<0.31.0)
+Project-URL: Documentation, https://github.com/lpalbou/meshvault/tree/main/docs
+Project-URL: Homepage, https://github.com/lpalbou/meshvault
+Project-URL: Repository, https://github.com/lpalbou/meshvault
+Description-Content-Type: text/markdown
+
+# MeshVault
+
+A professional, local web-based tool for rapidly browsing, previewing, and managing 3D assets (`.obj`, `.fbx`, `.gltf`, `.glb`, `.stl`) across your filesystem — including assets buried inside `.zip` and `.rar` archives.
+
+[![CI](https://github.com/lpalbou/meshvault/actions/workflows/ci.yml/badge.svg)](https://github.com/lpalbou/meshvault/actions)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
+[![FastAPI](https://img.shields.io/badge/backend-FastAPI-009688)](https://fastapi.tiangolo.com)
+[![Three.js](https://img.shields.io/badge/3D-Three.js%20r170-black)](https://threejs.org)
+[![PyPI](https://img.shields.io/pypi/v/meshvault)](https://pypi.org/project/meshvault/)
+[![npm](https://img.shields.io/npm/v/meshvault)](https://www.npmjs.com/package/meshvault)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Folder Browsing** | Navigate your filesystem with a clean sidebar tree. Go up, go home, double-click to enter. List/grid view toggle. |
+| **Search & Filter** | Real-time search input to filter folders and assets in the current directory. |
+| **3D Asset Detection** | Finds `.obj`, `.fbx`, `.gltf`, `.glb`, `.stl` files — including inside `.zip` and `.rar` archives. |
+| **Interactive 3D Viewer** | Click an asset to load it with high-quality PBR rendering, SSAO, soft shadows, tone mapping. |
+| **Orbit / FPV Toggle** | Orbit mode (mouse orbit/zoom/pan, right-click pivot) and FPV drone mode (WASD fly, A/D yaw, mouse look). |
+| **Viewer Toolbar** | Toggle grid, XYZ axes (colored + labeled), wireframe, and light controls from the top-right toolbar. |
+| **Light Controls** | Adjustable key/fill/ambient intensity, light direction (azimuth/elevation), and exposure. |
+| **Background Presets** | 12 background color swatches (dark, gray, light, tinted) for evaluating models on any backdrop. |
+| **Model Transforms** | Center at origin, ground on Y=0, auto-orient via PCA, reset to original. All without moving the camera. |
+| **Model Scaling** | Real-time scale slider (0.25×–2.0×). |
+| **Modified Export** | Export applies all transforms (center, ground, orient, scale) — saves modified OBJ via Three.js OBJExporter. |
+| **FBX Auto-Conversion** | Old FBX files (version < 7000) are auto-converted to OBJ via a built-in binary parser. |
+| **Persistent Settings** | Scene settings (wireframe, grid, axes, background) persist across model loads. |
+
+## Quick Start
+
+### Prerequisites
+
+- **Python 3.10+**
+- **Poetry** ([install guide](https://python-poetry.org/docs/#installation))
+- For `.rar` support, one of: `bsdtar`, `unrar`, `7z`, or `unar` (auto-detected)
+
+### Install & Run
+
+```bash
+git clone https://github.com/lpalbou/meshvault.git
+cd meshvault
+poetry install --no-root
+poetry run meshvault
+```
+
+Then open **http://localhost:8420** in your browser.
+
+### Install from PyPI
+
+```bash
+pip install meshvault
+meshvault
+```
+
+### Install from NPM
+
+```bash
+npx meshvault
+```
+
+## Usage
+
+1. **Browse**: Navigate folders in the sidebar. Toggle list/grid view. Filter by name.
+2. **Preview**: Click any 3D asset to load it in the viewer (green=OBJ, orange=FBX, cyan=GLTF, purple=STL/archived).
+3. **Navigate**: Orbit mode (left-drag orbit, scroll zoom, right-drag pan, right-click pivot) or FPV drone mode (W/Shift forward, S/Ctrl backward, A/D yaw, E/Q altitude). Spacebar resets camera.
+4. **Scene tools**: Toggle grid, axes (XYZ), wireframe, and lighting from the toolbar. Pick background color from swatches.
+5. **Transform**: Center model at origin, ground it on Y=0, or auto-orient via PCA. Reset undoes all transforms.
+6. **Export**: Set name and path in the top bar, click Export. Modified models (centered/oriented/scaled) are exported as OBJ with baked transforms.
+
+## Project Structure
+
+```
+meshvault/
+├── backend/
+│   ├── app.py                 # FastAPI server + routes
+│   ├── file_browser.py        # Filesystem navigation + asset discovery
+│   ├── archive_inspector.py   # ZIP/RAR inspection + multi-tool extraction
+│   ├── export_manager.py      # Asset export with renaming
+│   └── fbx_converter.py       # FBX 6100 binary parser + OBJ converter
+├── frontend/
+│   ├── index.html             # Main HTML page
+│   ├── css/styles.css         # Dark professional theme
+│   └── js/
+│       ├── app.js             # Main orchestrator
+│       ├── file_browser.js    # File browser + search + grid/list
+│       ├── viewer_3d.js       # Three.js 3D viewer
+│       └── export_panel.js    # Rename/export controls
+├── tests/
+│   └── test_file_browser.py   # Backend unit tests
+├── docs/                      # Full documentation
+├── pyproject.toml             # Poetry / PyPI configuration
+├── package.json               # NPM configuration
+└── poetry.lock
+```
+
+## Documentation
+
+- [Getting Started](docs/getting_started.md) — Installation, first run, basic usage
+- [Architecture](docs/architecture.md) — System design, components, design decisions
+- [API Reference](docs/api.md) — REST API endpoints, request/response schemas
+- [FAQ](docs/faq.md) — Common questions and troubleshooting
+
+## Tests
+
+```bash
+poetry run pytest tests/ -v
+```
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/lpalbou/meshvault).
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+© 2026 Laurent-Philippe Albou — contact@abstractcore.ai
+

meshvault-0.1.0/README.md

@@ -0,0 +1,121 @@
+# MeshVault
+
+A professional, local web-based tool for rapidly browsing, previewing, and managing 3D assets (`.obj`, `.fbx`, `.gltf`, `.glb`, `.stl`) across your filesystem — including assets buried inside `.zip` and `.rar` archives.
+
+[![CI](https://github.com/lpalbou/meshvault/actions/workflows/ci.yml/badge.svg)](https://github.com/lpalbou/meshvault/actions)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
+[![FastAPI](https://img.shields.io/badge/backend-FastAPI-009688)](https://fastapi.tiangolo.com)
+[![Three.js](https://img.shields.io/badge/3D-Three.js%20r170-black)](https://threejs.org)
+[![PyPI](https://img.shields.io/pypi/v/meshvault)](https://pypi.org/project/meshvault/)
+[![npm](https://img.shields.io/npm/v/meshvault)](https://www.npmjs.com/package/meshvault)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Folder Browsing** | Navigate your filesystem with a clean sidebar tree. Go up, go home, double-click to enter. List/grid view toggle. |
+| **Search & Filter** | Real-time search input to filter folders and assets in the current directory. |
+| **3D Asset Detection** | Finds `.obj`, `.fbx`, `.gltf`, `.glb`, `.stl` files — including inside `.zip` and `.rar` archives. |
+| **Interactive 3D Viewer** | Click an asset to load it with high-quality PBR rendering, SSAO, soft shadows, tone mapping. |
+| **Orbit / FPV Toggle** | Orbit mode (mouse orbit/zoom/pan, right-click pivot) and FPV drone mode (WASD fly, A/D yaw, mouse look). |
+| **Viewer Toolbar** | Toggle grid, XYZ axes (colored + labeled), wireframe, and light controls from the top-right toolbar. |
+| **Light Controls** | Adjustable key/fill/ambient intensity, light direction (azimuth/elevation), and exposure. |
+| **Background Presets** | 12 background color swatches (dark, gray, light, tinted) for evaluating models on any backdrop. |
+| **Model Transforms** | Center at origin, ground on Y=0, auto-orient via PCA, reset to original. All without moving the camera. |
+| **Model Scaling** | Real-time scale slider (0.25×–2.0×). |
+| **Modified Export** | Export applies all transforms (center, ground, orient, scale) — saves modified OBJ via Three.js OBJExporter. |
+| **FBX Auto-Conversion** | Old FBX files (version < 7000) are auto-converted to OBJ via a built-in binary parser. |
+| **Persistent Settings** | Scene settings (wireframe, grid, axes, background) persist across model loads. |
+
+## Quick Start
+
+### Prerequisites
+
+- **Python 3.10+**
+- **Poetry** ([install guide](https://python-poetry.org/docs/#installation))
+- For `.rar` support, one of: `bsdtar`, `unrar`, `7z`, or `unar` (auto-detected)
+
+### Install & Run
+
+```bash
+git clone https://github.com/lpalbou/meshvault.git
+cd meshvault
+poetry install --no-root
+poetry run meshvault
+```
+
+Then open **http://localhost:8420** in your browser.
+
+### Install from PyPI
+
+```bash
+pip install meshvault
+meshvault
+```
+
+### Install from NPM
+
+```bash
+npx meshvault
+```
+
+## Usage
+
+1. **Browse**: Navigate folders in the sidebar. Toggle list/grid view. Filter by name.
+2. **Preview**: Click any 3D asset to load it in the viewer (green=OBJ, orange=FBX, cyan=GLTF, purple=STL/archived).
+3. **Navigate**: Orbit mode (left-drag orbit, scroll zoom, right-drag pan, right-click pivot) or FPV drone mode (W/Shift forward, S/Ctrl backward, A/D yaw, E/Q altitude). Spacebar resets camera.
+4. **Scene tools**: Toggle grid, axes (XYZ), wireframe, and lighting from the toolbar. Pick background color from swatches.
+5. **Transform**: Center model at origin, ground it on Y=0, or auto-orient via PCA. Reset undoes all transforms.
+6. **Export**: Set name and path in the top bar, click Export. Modified models (centered/oriented/scaled) are exported as OBJ with baked transforms.
+
+## Project Structure
+
+```
+meshvault/
+├── backend/
+│   ├── app.py                 # FastAPI server + routes
+│   ├── file_browser.py        # Filesystem navigation + asset discovery
+│   ├── archive_inspector.py   # ZIP/RAR inspection + multi-tool extraction
+│   ├── export_manager.py      # Asset export with renaming
+│   └── fbx_converter.py       # FBX 6100 binary parser + OBJ converter
+├── frontend/
+│   ├── index.html             # Main HTML page
+│   ├── css/styles.css         # Dark professional theme
+│   └── js/
+│       ├── app.js             # Main orchestrator
+│       ├── file_browser.js    # File browser + search + grid/list
+│       ├── viewer_3d.js       # Three.js 3D viewer
+│       └── export_panel.js    # Rename/export controls
+├── tests/
+│   └── test_file_browser.py   # Backend unit tests
+├── docs/                      # Full documentation
+├── pyproject.toml             # Poetry / PyPI configuration
+├── package.json               # NPM configuration
+└── poetry.lock
+```
+
+## Documentation
+
+- [Getting Started](docs/getting_started.md) — Installation, first run, basic usage
+- [Architecture](docs/architecture.md) — System design, components, design decisions
+- [API Reference](docs/api.md) — REST API endpoints, request/response schemas
+- [FAQ](docs/faq.md) — Common questions and troubleshooting
+
+## Tests
+
+```bash
+poetry run pytest tests/ -v
+```
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/lpalbou/meshvault).
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+© 2026 Laurent-Philippe Albou — contact@abstractcore.ai

meshvault-0.1.0/backend/app.py

@@ -0,0 +1,393 @@
+"""
+Main FastAPI application - serves the 3D asset browser.
+
+This is the entry point that:
+- Serves the frontend static files
+- Provides REST API for file browsing, asset loading, and export
+- Manages the lifecycle of backend services
+"""
+
+import os
+import sys
+import mimetypes
+import urllib.parse
+from pathlib import Path
+from typing import Optional
+from contextlib import asynccontextmanager
+
+import uvicorn
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
+from pydantic import BaseModel
+
+from backend.file_browser import FileBrowser
+from backend.archive_inspector import ArchiveInspector
+from backend.export_manager import ExportManager
+from backend.fbx_converter import get_fbx_version, convert_fbx_to_obj
+
+
+# --- Configuration ---
+
+# Default browse root: user's home directory
+DEFAULT_ROOT = str(Path.home())
+
+# Register additional MIME types for 3D files
+mimetypes.add_type("model/obj", ".obj")
+mimetypes.add_type("model/fbx", ".fbx")
+mimetypes.add_type("model/mtl", ".mtl")
+mimetypes.add_type("model/gltf+json", ".gltf")
+mimetypes.add_type("model/gltf-binary", ".glb")
+mimetypes.add_type("model/stl", ".stl")
+
+
+# --- Pydantic models for API ---
+
+class ExportRequest(BaseModel):
+    """Request body for exporting an asset."""
+    source_path: str
+    target_dir: str
+    new_name: str
+    is_in_archive: bool = False
+    archive_path: Optional[str] = None
+    inner_path: Optional[str] = None
+    related_files: list[str] = []
+
+
+class ExportModifiedRequest(BaseModel):
+    """Request body for exporting a modified model (OBJ text from frontend)."""
+    target_dir: str
+    new_name: str
+    obj_content: str
+
+
+class BrowseResponse(BaseModel):
+    """Response for browse endpoint."""
+    current_path: str
+    parent_path: Optional[str]
+    folders: list[dict]
+    assets: list[dict]
+
+
+# --- App lifecycle ---
+
+archive_inspector = ArchiveInspector()
+file_browser = FileBrowser()
+export_manager = ExportManager()
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Manage application lifecycle — clean up temp files on shutdown."""
+    yield
+    archive_inspector.cleanup()
+
+
+# --- FastAPI App ---
+
+app = FastAPI(
+    title="MeshVault",
+    description="Professional 3D asset browser for rapid management",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+# Serve frontend static files
+# Works both in development (project root) and when installed via pip
+# (frontend/ is installed alongside backend/ in site-packages parent)
+_project_root = Path(__file__).parent.parent
+frontend_dir = _project_root / "frontend"
+if not frontend_dir.exists():
+    # Fallback: check if installed as a package (site-packages layout)
+    import importlib.resources
+    try:
+        frontend_dir = Path(importlib.resources.files("frontend"))
+    except Exception:
+        pass
+app.mount(
+    "/static",
+    StaticFiles(directory=str(frontend_dir)),
+    name="static",
+)
+
+
+# --- Routes ---
+
+@app.get("/", response_class=HTMLResponse)
+async def root():
+    """Serve the main HTML page."""
+    index_path = frontend_dir / "index.html"
+    return HTMLResponse(content=index_path.read_text(encoding="utf-8"))
+
+
+@app.get("/api/browse")
+async def browse(path: Optional[str] = Query(default=None)):
+    """
+    Browse a directory and return its contents.
+
+    Query params:
+        path: Directory path to browse. Defaults to user's home.
+    """
+    browse_path = path or DEFAULT_ROOT
+
+    try:
+        result = file_browser.browse(browse_path)
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except ValueError as e:
+        raise HTTPException(status_code=403, detail=str(e))
+
+    return {
+        "current_path": result.current_path,
+        "parent_path": result.parent_path,
+        "folders": [
+            {
+                "name": f.name,
+                "path": f.path,
+                "has_children": f.has_children,
+            }
+            for f in result.folders
+        ],
+        "assets": [
+            {
+                "name": a.name,
+                "path": a.path,
+                "extension": a.extension,
+                "size": a.size,
+                "is_in_archive": a.is_in_archive,
+                "archive_path": a.archive_path,
+                "inner_path": a.inner_path,
+                "related_files": a.related_files,
+            }
+            for a in result.assets
+        ],
+    }
+
+
+def _maybe_convert_fbx(file_path: Path) -> tuple[Path, str]:
+    """
+    Check if an FBX file needs conversion (version < 7000) and convert it.
+
+    Returns (path_to_serve, extension) — if converted, path points to the
+    generated OBJ file and extension is ".obj". Otherwise returns the
+    original path and extension unchanged.
+    """
+    ext = file_path.suffix.lower()
+    if ext != ".fbx":
+        return file_path, ext
+
+    version = get_fbx_version(str(file_path))
+    if version is not None and version < 7000:
+        # FBX version too old for Three.js — convert to OBJ
+        obj_path = file_path.with_suffix(".converted.obj")
+        if not obj_path.exists():
+            success = convert_fbx_to_obj(str(file_path), str(obj_path))
+            if not success:
+                # Conversion failed — let the frontend try anyway
+                return file_path, ext
+        return obj_path, ".obj"
+
+    return file_path, ext
+
+
+@app.get("/api/asset/file")
+async def serve_asset_file(path: str = Query(...)):
+    """
+    Serve a 3D asset file for the viewer.
+
+    For regular files, serves directly.
+    For FBX files with version < 7000, auto-converts to OBJ.
+    """
+    file_path = Path(path)
+    if file_path.exists() and file_path.is_file():
+        # Auto-convert old FBX if needed
+        serve_path, _ = _maybe_convert_fbx(file_path)
+        content_type = mimetypes.guess_type(str(serve_path))[0] or "application/octet-stream"
+        return FileResponse(
+            path=str(serve_path),
+            media_type=content_type,
+            filename=serve_path.name,
+        )
+
+    raise HTTPException(status_code=404, detail=f"File not found: {path}")
+
+
+@app.get("/api/asset/archive")
+async def serve_archive_asset(
+    archive_path: str = Query(...),
+    inner_path: str = Query(...),
+):
+    """
+    Extract and serve a 3D asset from an archive.
+
+    Extracts the asset (and related files) to a temp directory,
+    then serves the main asset file.
+    """
+    extracted = archive_inspector.extract_asset(archive_path, inner_path)
+    if extracted is None:
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to extract {inner_path} from {archive_path}",
+        )
+
+    file_path = Path(extracted)
+    if not file_path.exists():
+        raise HTTPException(status_code=404, detail="Extracted file not found")
+
+    content_type = mimetypes.guess_type(str(file_path))[0] or "application/octet-stream"
+    return FileResponse(
+        path=str(file_path),
+        media_type=content_type,
+        filename=file_path.name,
+    )
+
+
+@app.get("/api/asset/prepare_archive")
+async def prepare_archive_asset(
+    archive_path: str = Query(...),
+    inner_path: str = Query(...),
+):
+    """
+    Extract an archived asset and return JSON with resolved temp paths.
+
+    This endpoint extracts the main asset and its related files to a
+    temp directory, then returns the absolute filesystem paths so the
+    frontend can use /api/asset/file and /api/asset/related with them.
+
+    This solves the problem of archive-internal paths not being valid
+    filesystem paths for the Three.js loaders.
+    """
+    extracted = archive_inspector.extract_asset(archive_path, inner_path)
+    if extracted is None:
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to extract {inner_path} from {archive_path}",
+        )
+
+    file_path = Path(extracted)
+    if not file_path.exists():
+        raise HTTPException(status_code=404, detail="Extracted file not found")
+
+    # Auto-convert old FBX if needed
+    serve_path, actual_ext = _maybe_convert_fbx(file_path)
+
+    # Build the file URL for the main asset (points to converted file if applicable)
+    file_url = f"/api/asset/file?path={urllib.parse.quote(str(serve_path))}"
+
+    # Resolve related file paths: map archive-internal -> extracted temp paths
+    # First, get all related files from the archive listing
+    result = file_browser.browse(str(Path(archive_path).parent))
+    archived_asset = None
+    for a in result.assets:
+        if (a.archive_path == archive_path and a.inner_path == inner_path):
+            archived_asset = a
+            break
+
+    related_inner = archived_asset.related_files if archived_asset else []
+    related_resolved = archive_inspector.get_extracted_related_paths(
+        archive_path, related_inner
+    )
+
+    return {
+        "file_url": file_url,
+        "file_path": str(serve_path),
+        "related_files": related_resolved,
+        # Tell frontend the actual format to use (may differ if converted)
+        "actual_extension": actual_ext,
+    }
+
+
+@app.get("/api/asset/related")
+async def serve_related_file(path: str = Query(...)):
+    """
+    Serve a related file (texture, material) for the 3D viewer.
+
+    This endpoint allows the Three.js loaders to fetch .mtl files,
+    textures, etc., that are referenced by the main 3D asset.
+    """
+    file_path = Path(path)
+    if not file_path.exists():
+        raise HTTPException(status_code=404, detail=f"File not found: {path}")
+
+    content_type = mimetypes.guess_type(str(file_path))[0] or "application/octet-stream"
+    return FileResponse(
+        path=str(file_path),
+        media_type=content_type,
+        filename=file_path.name,
+    )
+
+
+@app.post("/api/export")
+async def export_asset(request: ExportRequest):
+    """
+    Export a 3D asset to a target directory with a new name.
+
+    Handles both regular files and archived assets.
+    """
+    result = export_manager.export_asset(
+        source_path=request.source_path,
+        target_dir=request.target_dir,
+        new_name=request.new_name,
+        is_in_archive=request.is_in_archive,
+        archive_path=request.archive_path,
+        inner_path=request.inner_path,
+        related_files=request.related_files,
+    )
+
+    if not result.success:
+        raise HTTPException(status_code=500, detail=result.message)
+
+    return {
+        "success": result.success,
+        "output_path": result.output_path,
+        "message": result.message,
+        "files_exported": result.files_exported,
+    }
+
+
+@app.post("/api/export_modified")
+async def export_modified(request: ExportModifiedRequest):
+    """
+    Export a modified model (OBJ text generated by the frontend).
+
+    This is used when the user has recentered, auto-oriented, or scaled
+    the model in the viewer and wants to export the modified version.
+    """
+    target_dir = Path(request.target_dir)
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    obj_path = target_dir / f"{request.new_name}.obj"
+    try:
+        obj_path.write_text(request.obj_content, encoding="utf-8")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to write: {e}")
+
+    return {
+        "success": True,
+        "output_path": str(target_dir),
+        "message": f"Exported modified model as OBJ",
+        "files_exported": [str(obj_path)],
+    }
+
+
+@app.get("/api/default_path")
+async def get_default_path():
+    """Return the default browse path (user home)."""
+    return {"path": DEFAULT_ROOT}
+
+
+def main():
+    """Entry point for running the server."""
+    port = int(os.environ.get("PORT", 8420))
+    print(f"\n  🎨 MeshVault")
+    print(f"  → Open http://localhost:{port} in your browser\n")
+    uvicorn.run(
+        "backend.app:app",
+        host="0.0.0.0",
+        port=port,
+        reload=False,
+    )
+
+
+if __name__ == "__main__":
+    main()