Skip to content

feat(view): show a local .glb/.gltf in a browser viewer - #54

Merged
Arlieeee merged 2 commits into
mainfrom
feat/view-command
Nov 14, 2026
Merged

Arlieeee merged 2 commits into
mainfrom
feat/view-command

Conversation

@Arlieeee

@Arlieeee Arlieeee commented Nov 14, 2026 •

Copy link
Copy Markdown
Collaborator

Adds meshy view, a local 3D viewer for a delivered model. Agents can use it to show the model in hosts whose file view cannot display a .glb, such as a browser panel next to the chat.

Added

  • meshy view <model>: serves one local .glb or .gltf read-only on 127.0.0.1 and opens a three.js viewer page in the browser (rotate, zoom, first animation clip).
    • --detach runs the server in a background process and returns result.url and result.pid at once.
    • --no-open prints the URL without opening a browser.
    • It stops after 30 minutes without a request, or on Ctrl-C.
  • A file without materials (an untextured preview) renders as matte grey clay, and normals a mesh leaves out are computed, so previews show their shape instead of a flat white silhouette.
  • What the server reads: the model, and for a .gltf the buffers and textures inside its folder. It never reads sidecars, other files or links that point out of the folder. It answers only GET and HEAD with a loopback Host header.
  • The page loads three.js 0.170 from jsDelivr, with SRI hashes in the import map. The lighting environment ships in the package as assets/viewer-env.hdr (about 0.5 MB, built from Poly Haven's CC0 "Decor Shop" by scripts/make-viewer-env.mjs).
  • D-094 in docs/decisions.md, plus tests/view.test.ts. README, meshy resources and the bundled skill mention the command.

Testing

  • npm run typecheck and npm test pass: 709, 0 failed.
  • Checked by hand in a browser with a textured model and two untextured previews, in both detached and foreground mode, and in an agent chat whose browser panel opened the URL.

`meshy view <model>` serves one local model read-only on 127.0.0.1 and
opens a three.js viewer page with a neutral studio look (Neutral tone
mapping, a studio environment, key light and soft ground shadow).
`--detach` serves from a background process and returns the URL in the
envelope at once; `--no-open` skips the browser. Local only: no API call,
no credential. The server stops after 30 minutes without a request.

three.js 0.170 loads from jsDelivr with SRI hashes in the import map; the
lighting environment ships in the package (assets/viewer-env.hdr, built
from Poly Haven's CC0 "Decor Shop" by scripts/make-viewer-env.mjs).
See D-094.
A file without materials got glTF's default material (white, fully
metallic), and a mesh without normals had no shading, so untextured
previews showed as a flat, overexposed shape. Such files now render as
matte grey clay, and missing normals are computed. The fill lights are
lowered so a white surface stays below clipping.
@Arlieeee
Arlieeee merged commit e3bac10 into main Nov 14, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant