# MeshVault

> MeshVault is a local-first 3D asset browser and viewer with an embeddable, server-less
> viewer core that exposes a self-describing control API designed to be driven by AI
> agents. An agent can load a model, find and frame its semantic "front", inspect the mesh,
> take cross-sections, and capture hero shots — all through one JSON command interface.

Key facts for agents:
- The standalone viewer runs with no backend. Load it as an ES module
  (`import { createViewer } from ".../meshvault-viewer.js"`) or via the global
  `window.MeshVaultViewer.createViewer(container)`. A live demo/harness is at `/static/viewer.html`
  where `window.mv` is the API instance.
- Everything is driven through ONE entry point: `api.execute({ action, params }) → { ok, result | error }`.
  It never throws; errors are structured strings. Discover all commands and their parameter
  schemas at runtime with `api.listCommands()`.
- Observe state (JSON, no vision needed) with `api.getState()`, `api.getSceneInfo()`, and the
  `get_bounds` command. Capture what the viewer sees with `screenshot` (returns a PNG data URL).
- Best first move after loading: `describe_scene` — one structured snapshot (summary sentence,
  inventory, size hint, hierarchy, materials, detected geometry issues, current view) so you can
  reason about the model without any screenshot.
- Explore parts: describe_scene gives each mesh a stable `id` + world `center`/`size`;
  `focus {id}` (or name/point) frames that part — even tiny ones — keeping the view direction.
  `reset_camera` returns to the whole model.
- "front/back/left/right" presets are WORLD-AXIS conventions and are often wrong for
  mis-oriented models. To find a model's real front, use `find_best_view` (scores angles by
  lighting-independent visible detail and auto-uprights the camera).
- Compressed glTF (Draco geometry, KTX2/Basis textures, Meshopt) loads transparently;
  decoders are bundled locally (offline-safe, no CDN).
- Image-based lighting (IBL) is on by default for realistic PBR reflections; control it
  with `set_environment { enabled, intensity, asBackground }` / `get_environment`.

- MCP: agents can drive MeshVault natively via the bundled MCP server (`meshvault-mcp`,
  13 tools: load_model [URL or local path; multi-file OBJ/FBX/gltf assets load
  textured; add:true composes multi-object scenes], describe_scene, viewer_execute,
  list_viewer_commands, get_state, compare_models [geometric shape registration],
  screenshot [presets for comparable renders; times:[...] motion contact sheets],
  get_texture [texture-space views: UV wireframe, markers, chart outline, crop],
  export_model [GLB file export: animation + texture tiers],
  save_scene/load_scene [.mvscene manifests persist composed scenes],
  open_in_app [push your model + camera into the running app so a human co-views
  live], get_app_state [read what the HUMAN is looking at — path + camera — and
  continue their session headless]).
  See https://github.com/lpalbou/MeshVault/blob/main/docs/mcp.md.
- Scene composition: `load` replaces, `add_model` composes; per-object placement via
  set_object_transform (wrapper transforms, never baked); single-object commands act
  on the ACTIVE object (set_active_object); frame_all or orbit/set_view with
  scope:"scene" for scene-wide framing; get_scene_manifest serializes the composition.
- Creation: agents can BUILD from nothing — `add_primitive` (7 kinds, paint-safe UV
  atlases, exact colors), `sculpt`/`sculpt_stroke` (6 world-space brushes, welded
  seam-safe edits, quantified {affected, maxDisplacement, newSize} returns),
  `paint`/`paint_stroke`/`fill_paint`/`clear_paint` (real texture layers; honest
  {painted, meanAlpha} feedback; shape:"square" quads; max_normal_angle edge clamp),
  `pick`/`raycast` (screenshot/world coords → surface points — the hand-eye loop),
  and `batch` (≤32 commands per round-trip). Sculpt+paint persist via export_glb.
- Repair & adaptive LoD: `inspect_region` (density survey, opportunity-sorted grid)
  → `simplify_region` (boundary-locked regional decimation — adaptive resolution by
  agent judgment), `fix_mesh` (degenerate/normals/flipped-face passes with issue
  deltas), `inspect_texture` (texel density + worst spots), `blur_paint`/`clone_paint`,
  `detect_symmetry`/`mirror_paint` (heal from the object's own mirror counterpart),
  `undo_paint` (single-slot brush undo — a bad stamp is not a one-way door)
  (defect softening + world-space heal brush), texture tiers low/medium/high/xhigh
  (512→4096) on paint and on export.
- Articulation & animation: `detect_parts`/`split_object` (plane cuts with suggested
  pivots — fused image-to-3D meshes articulate this way), `set_parent`/`set_pivot`
  (hierarchies + rotation origins), `set_keyframe`/`play`/`seek_timeline` (scene
  timeline, deterministic seeks, short-arc + 360°-identity teaching), motion contact
  sheets (MCP screenshot times:[...]), animated GLB export (export_model), timeline
  UI bar for humans, `.mvscene` v2 persistence.
- REST screenshot (local server, no MCP needed): `GET /api/screenshot?path=/abs/
  model.glb&best_view=true&preset=studio` returns a PNG (token header required;
  metadata in the X-MeshVault-Screenshot header). Docs: docs/api.md.
- Deep links (local app): `/?path=/abs/model.glb` selects + loads an asset;
  `/?dir=/abs/folder` opens a folder; `/?path=/abs/pack.zip!inner/model.obj` loads an
  archive member; `/?scene=/abs/file.mvscene` rebuilds a composed scene. URL params
  win over the remembered last directory, and the URL stays in sync while browsing —
  the address bar is always a shareable deep link.
- A hosted, zero-install build of this viewer (same window.mv control API, URL-loading
  only, no backend tools) is live at https://www.lpalbou.info/MeshVault/ with its own
  llms.txt for the remote context.

## Docs

- [Control API reference (full)](/llms-full.txt): Every command, parameters, return shapes, and worked examples for driving the viewer.
- [MCP server](https://github.com/lpalbou/MeshVault/blob/main/docs/mcp.md): Drive the viewer from Claude/Cursor via Model Context Protocol — install, client config, tools.
- [MCP usage examples](https://github.com/lpalbou/MeshVault/tree/main/examples/mcp): Runnable agent workflows (inspect, compare iterations, explore parts, hero shots).
- [Architecture](https://github.com/lpalbou/MeshVault/blob/main/docs/architecture.md): System design, the viewer core / control API / standalone bundle, and the backend.
- [API Reference (backend REST)](https://github.com/lpalbou/MeshVault/blob/main/docs/api.md): The local server's HTTP endpoints and security model.
- [Getting Started](https://github.com/lpalbou/MeshVault/blob/main/docs/getting_started.md): Install, run, UI overview.

## Optional

- [FAQ](https://github.com/lpalbou/MeshVault/blob/main/docs/faq.md): Formats, troubleshooting, dev/build notes.
- [Demo harness](/static/viewer.html): Live standalone viewer exposing `window.mv`.
