@blendviewer/vision-scope

Universal file viewer SDK — detect file types and render images, media, code, documents, archives, textures, and 3D spatial assets.

Installation

npm install @blendviewer/vision-scope
# or
yarn add @blendviewer/vision-scope
# or
pnpm add @blendviewer/vision-scope

Usage

Basic Example

import { VisionScope } from '@blendviewer/vision-scope';
import '@blendviewer/vision-scope/styles.css'; // Required: CSS is not injected automatically

const scope = new VisionScope({
  container: document.getElementById('viewer'), // or a selector like '#viewer'
  ui: true,
});

// Load a file by URL or file
await scope.load('https://example.com/path/to/file.glb');
// await scope.load('/path/to/file.glb');

Host integration (read this when embedding in your app)

You only need a sized container plus the two imports above. You do not need to change your Tailwind, global pre/code styles, or add CSS prefixes for Vision Scope.

Full notes (CSS boundary, flex layout, CORS, React/Next.js, troubleshooting): docs/HOST_INTEGRATION.md

Third-party renderer CSS (Prism, Plyr, spreadsheets) is bundled in styles.css and prefixed with .vision-scope-root at build time — hosts do not import those libraries separately.

Live Demo

Try the live playground: vision-scope.blendviewer.com

• PDF Document
• PPTX Powerpoint
• 3D Model (GLB)

Share links with ?file= query parameters, for example:

• https://your-domain.example/?file=./dist/samples/readme-sample.md
• https://your-domain.example/?file=https://oss.blendviewer.com/public/57f41350-1e82-11ef-b5e1-03b42f41a1d3/bee.glb

(Note: Ensure CORS is enabled on the target server if loading your own remote URLs).

Supported File Types

Vision Scope comes with built-in renderers for a wide variety of file formats:

• Images: jpg, jpeg, png, webp, gif, bmp, tif, tiff, svg
• 3D Spatial / Models: glb, gltf, fbx, obj, stl, 3ds, 3dm, 3mf, dae, amf, bvh, drc, gcode, ifc, kmz, lwo, md2, mdd, mmd, pmx, mpd, nrrd, pdb, tilt, ttf, usdz, vox, vrml, wrl, vtk, xyz
• CAD: dwg, dxf, step, stp, iges, igs, brep, brp (STEP/IGES/BREP via occt-import-js in BlendViewer/OV)
• Point Cloud: pcd, ply, las, laz (LAS/LAZ via @loaders.gl/las, auto-decimated for large files)
• GPU Textures: ktx2, basis
• Documents: pdf, doc, pptx, ppt, txt, md — .docx via Hub plugin com.blendviewer.vision-docx
• Tabular / Spreadsheets: csv, tsv, xlsx, xls, ods
• Media (Video/Audio): mp4, webm, avi, mov, mkv, mp3, wav, flac, aac, ogg
• Code & Text: js, ts, jsx, tsx, py, java, go, rs, c, cpp, html, css, json, yaml, xml, sql, sh, dockerfile, and many more.
• Archives: zip, rar, 7z, tar, gz (with inner file type detection, e.g., model.glb.zip)

Scope Extensions (Plugins)

Hub plugins declare handled formats in scopeExtension.formats[] (one object per extension). Do not add plugin-only types to FileTypeDetector.

export const scopeExtension = {
  id: 'com.example.my-viewer',
  formats: [
    { ext: 'docx', kind: 'document', subtype: 'word', mime: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' },
  ],
  mountPreview(container, context) {
    return { destroy() {} };
  },
};

Register at runtime:

import { VisionScope } from '@blendviewer/vision-scope';

VisionScope.registerExtension(scopeExtension);
await VisionScope.registerExtensionModule(() => import('./path/to/plugin.js'));

| Field | Required | Purpose | |-------|----------|---------| | formats[].ext | yes | Extension without dot — routing + detection | | formats[].kind | yes | Semantic category (document, tabular, spatial, …) | | formats[].mime | no | MIME routing when extension is missing | | formats[].subtype | no | Display / logging hint | | rendererKey | no | RendererFactory key; defaults to scope:<id> | | mountPreview | yes* | Preview UI (*or createRendererClass) |

Built-in types stay in FileTypeDetector. Hosts use detectFileTypeFromExtension() and archiveFileIconSvg() to merge built-in + plugin metadata.