dsh-blend-preview

Preview Blender .blend files inside DeepSeek Harness: the right-Sidebar document preview turns the scene into an interactive 3D viewport (orbit / zoom / wireframe) with a scene-information panel, instead of the built-in “binary file, no preview” empty state.

What it does

• Registers a document-preview renderer for .blend files, so clicking one in Workspace files opens it in the right Sidebar.
• Runs blender --background once per file version to export a GLB plus a scene JSON (objects, triangles, materials, real-world size in mm, units, cameras, lights, collections).
• Draws the GLB with a small dependency-free WebGL viewer written for this plugin: orbit, pan, wheel zoom, double-click reset, wireframe mode, auto-rotate, a soft contact shadow and an axis triad. No CDN, no three.js.
• Caches conversions under ~/.dsh/cache/blend-preview; the second open is instant (a few milliseconds).
• Shows the scene facts that matter for CAD/3D-printing work: per-object triangle counts and bounding-box sizes in millimetres, material swatches, scene units.

Requirements

• DeepSeek Harness 0.2.x (declared compatible with 0.2.0-rc.2 and 0.2.1-rc.2).
• Blender 3.6 / 4.x / 5.x installed. The plugin auto-detects DSH_BLENDER, BLENDER_PATH, blender on PATH, the Steam library, and C:\Program Files\Blender Foundation\Blender*. Set blenderPath if your install lives elsewhere.
• A browser/GPU with WebGL (the DSH desktop app always has it).

Install

# into a normal (non-desktop) profile
dsh plugin --profile <profile> add dsh-blend-preview

# the desktop profile is owned by the Electron app; add it there through the
# plugin manager UI, or compose it manually and restart the app

The package ships a cordis.patch.yml, so installation adds the plugin row automatically. Restart DSH after installing.

Configuration

Settings → Plugins → Blender preview (namespace blend-preview):

| Key | Default | Meaning | |---|---|---| | enabled | true | Register the renderer and the conversion route. | | routePath | /api/blend-preview | Authenticated conversion route. Must stay under /api; otherwise the authenticated fence is bypassed, so it falls back to the default. | | extensions | ["blend"] | Suffixes that open in the 3D preview. | | blenderPath | "" (auto) | Absolute path of blender.exe / blender. | | cacheDir | "" → ~/.dsh/cache/blend-preview | Where exported GLB files and scene JSON live. | | timeoutMs | 180000 | Wall-clock ceiling for one cold conversion. | | maxBytes | 1073741824 | Largest .blend converted (1 GiB). | | applyModifiers | true | Apply modifiers during export, so the preview matches what Blender renders. | | cacheEntries | 24 | Cached conversions kept on disk before the oldest are pruned. |

How it works

Workspace file click
        │
        ▼
document preview body (lib/client.js)
        │  GET /api/blend-preview?path=…&kind=info   (scene JSON)
        │  GET /api/blend-preview?path=…&kind=glb    (model bytes)
        ▼
Host half (lib/index.js, lib/route.js)
        │  cache key = sha1(realpath, size, mtime, recipe, modifiers)
        ▼
lib/blender.js ── spawn blender --background --python lib/scene.py
        │            → model.glb + scene.json (+ meta.json)
        ▼
~/.dsh/cache/blend-preview/<key>/

• lib/scene.py exports with export_apply, use_visible, Y-up, no cameras/lights, and writes the scene description (world-space AABBs through the evaluated depsgraph, Principled base colours converted to sRGB swatches).
• The route lives under /api, so the connection service authenticates every request (Host/Origin fence + session cookie). Arbitrary local files are not exposed.
• The viewer is a hand-written glTF 2.0 subset renderer (POSITION + NORMAL, indexed triangles, PBR factors, node TRS/matrix). Textures, skinning and animation are out of scope; the Host only exports still scenes.

Development

dev/client-body.js   client UI (single CJS factory for the DSH module loader)
dev/viewer.js        the WebGL renderer, spliced into the bundle at build time
scripts/build-client.mjs   builds lib/client.js from the two files
scripts/e2e-browser.mjs    Playwright end-to-end against a temporary DSH host
scripts/live-selftest.mjs  cold/warm/concurrent conversion against a real .blend
node --test test/*.test.js

lib/client.js is generated — edit the files under dev/ and rebuild. The DSH client loader hands the bundle a require limited to the platform seed modules, so the package cannot pull a renderer dependency at runtime; the single generated file is the intended shape.

Notes and limits

• A cold conversion takes roughly 2–10 s for a small scene (Blender startup dominates); it is cached per file version, so rotating/zooming never re-runs Blender.
• Very large scenes (millions of triangles) export slowly and may exceed timeoutMs.
• Textures are not shown in the viewport (base colours only); the Blender renders next to the file are still the reference.
• Nothing is uploaded: Blender runs locally and the GLB stays in the local cache.