@blendviewer/vision-scope 0.1.0

package/README.md

@@ -0,0 +1,95 @@
+# @blendviewer/vision-scope
+
+Universal file viewer SDK — detect file types and render images, media, code, documents, archives, textures, and 3D spatial assets.
+
+## Installation
+
+```bash
+npm install @blendviewer/vision-scope
+# or
+yarn add @blendviewer/vision-scope
+# or
+pnpm add @blendviewer/vision-scope
+```
+
+## Usage
+
+### Basic Example
+
+```javascript
+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');
+```
+
+### Live Demo
+
+Try the live playground: **[vision-scope.blendviewer.com](https://vision-scope.blendviewer.com)**
+
+- [PDF Document](https://vision-scope.blendviewer.com/?file=https://oss.blendviewer.com/public/788d77d0-1d49-11ef-861a-b3174c760332/math/9912/9912227v2.pdf)
+- [3D Model (GLB)](https://vision-scope.blendviewer.com/?file=https://oss.blendviewer.com/public/57f41350-1e82-11ef-b5e1-03b42f41a1d3/bee.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`
+- **Point Cloud**: `pcd`, `ply`, `las`
+- **GPU Textures**: `ktx2`, `basis`
+- **Documents**: `pdf`, `docx`, `doc`, `pptx`, `ppt`, `txt`, `md`
+- **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)
+
+Vision Hub plugins can extend file preview capabilities beyond built-in types. You can export an extension from your plugin module:
+
+```javascript
+export const scopeExtension = {
+  id: 'com.example.my-viewer',
+  extensions: ['h5', 'hdf5'],
+  mountPreview(container, context) {
+    // context.url, context.filename, context.readOnly, etc.
+    // Initialize your custom viewer here
+
+    return {
+      destroy() {
+        // Cleanup resources when the viewer is unmounted
+      },
+    };
+  },
+};
+```
+
+Register the extension at runtime:
+
+```javascript
+import { VisionScope } from '@blendviewer/vision-scope';
+
+// Register a static extension object
+VisionScope.registerExtension(scopeExtension);
+
+// Or register via dynamic import
+await VisionScope.registerExtensionModule(() => import('./path/to/plugin.js'));
+```
+
+Built-in routing uses a file type detector first; unknown extensions fall through to the extension registry.