openscad-viewer 2026.2.1

package/README.md

@@ -0,0 +1,17 @@
+# openscad-viewer
+Simple openscad model viewer with camera controls.
+
+## Features
+* Browser UI
+  * Render the model (put the file-name in the title bar)
+  * Camera controls: zoom, pan, rotate
+* MCP tools
+  * `open` opens a model file to the viewer
+  * `view` get a rendered image at a particular angle and distance
+* Interaction
+  * when a `view` request is made the UI updates;  i.e. the user "sees" what the agent is looking at
+  * when the model file changes the UI updates automatically
+
+## Architecture
+* Run via `npx openscad-viewer`
+* Nodejs + express + react

package/index.js

@@ -0,0 +1,430 @@
+#!/usr/bin/env node
+
+const express = require('express');
+const http = require('http');
+const { WebSocketServer } = require('ws');
+const chokidar = require('chokidar');
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+const fs = require('fs');
+const fsp = require('fs/promises');
+const path = require('path');
+const os = require('os');
+
+const execFileAsync = promisify(execFile);
+const PORT = 8439;
+
+// Redirect all logging to stderr (stdout is reserved for MCP stdio transport)
+const log = (...args) => process.stderr.write(`[openscad-viewer] ${args.join(' ')}\n`);
+
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+let currentFile = null;
+let currentStlPath = null;
+let currentStlBuffer = null;
+let lastBoundingBox = null;
+let watcher = null;
+let debounceTimer = null;
+
+const wsClients = new Set();
+const pendingRequests = new Map();
+let requestIdCounter = 0;
+
+// ---------------------------------------------------------------------------
+// OpenSCAD helpers
+// ---------------------------------------------------------------------------
+
+function checkOpenSCAD() {
+  return new Promise((resolve) => {
+    execFile('openscad', ['--version'], (err) => resolve(!err));
+  });
+}
+
+async function compileScad(scadPath) {
+  const tmpStl = path.join(os.tmpdir(), `openscad-viewer-${Date.now()}.stl`);
+  try {
+    await execFileAsync('openscad', ['-o', tmpStl, scadPath], { timeout: 60000 });
+    return { stlPath: tmpStl, error: null };
+  } catch (err) {
+    return { stlPath: null, error: err.stderr || err.message };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// STL bounding-box parser (binary + ASCII)
+// ---------------------------------------------------------------------------
+
+function parseStlBoundingBox(buffer) {
+  const min = [Infinity, Infinity, Infinity];
+  const max = [-Infinity, -Infinity, -Infinity];
+
+  // Try binary STL
+  if (buffer.length >= 84) {
+    const numTriangles = buffer.readUInt32LE(80);
+    const expectedSize = 84 + numTriangles * 50;
+
+    if (numTriangles > 0 && buffer.length >= expectedSize) {
+      for (let i = 0; i < numTriangles; i++) {
+        const base = 84 + i * 50 + 12; // skip normal vector
+        for (let v = 0; v < 3; v++) {
+          const off = base + v * 12;
+          const x = buffer.readFloatLE(off);
+          const y = buffer.readFloatLE(off + 4);
+          const z = buffer.readFloatLE(off + 8);
+          min[0] = Math.min(min[0], x);  max[0] = Math.max(max[0], x);
+          min[1] = Math.min(min[1], y);  max[1] = Math.max(max[1], y);
+          min[2] = Math.min(min[2], z);  max[2] = Math.max(max[2], z);
+        }
+      }
+      if (min[0] !== Infinity) return { min, max };
+    }
+  }
+
+  // ASCII fallback
+  const text = buffer.toString('utf8');
+  const re = /vertex\s+([-\d.eE+]+)\s+([-\d.eE+]+)\s+([-\d.eE+]+)/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const x = parseFloat(m[1]), y = parseFloat(m[2]), z = parseFloat(m[3]);
+    min[0] = Math.min(min[0], x);  max[0] = Math.max(max[0], x);
+    min[1] = Math.min(min[1], y);  max[1] = Math.max(max[1], y);
+    min[2] = Math.min(min[2], z);  max[2] = Math.max(max[2], z);
+  }
+  return { min, max };
+}
+
+// ---------------------------------------------------------------------------
+// Dependency parsing for .scad files
+// ---------------------------------------------------------------------------
+
+function parseScadDependencies(scadPath) {
+  try {
+    const content = fs.readFileSync(scadPath, 'utf8');
+    const deps = [];
+    const re = /(?:include|use)\s*<([^>]+)>/g;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+      const dep = path.resolve(path.dirname(scadPath), m[1]);
+      if (fs.existsSync(dep)) deps.push(dep);
+    }
+    return deps;
+  } catch {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// WebSocket helpers
+// ---------------------------------------------------------------------------
+
+function broadcast(msg) {
+  const data = JSON.stringify(msg);
+  for (const ws of wsClients) {
+    if (ws.readyState === 1) ws.send(data);
+  }
+}
+
+function sendAndWait(msg, timeoutMs = 10000) {
+  return new Promise((resolve, reject) => {
+    const requestId = ++requestIdCounter;
+    msg.requestId = requestId;
+
+    const timer = setTimeout(() => {
+      pendingRequests.delete(requestId);
+      reject(new Error('Timeout waiting for browser response'));
+    }, timeoutMs);
+
+    pendingRequests.set(requestId, {
+      resolve(data) { clearTimeout(timer); pendingRequests.delete(requestId); resolve(data); },
+      reject(err)   { clearTimeout(timer); pendingRequests.delete(requestId); reject(err); },
+    });
+
+    const data = JSON.stringify(msg);
+    for (const ws of wsClients) {
+      if (ws.readyState === 1) { ws.send(data); return; }
+    }
+
+    clearTimeout(timer);
+    pendingRequests.delete(requestId);
+    reject(new Error('No browser connected'));
+  });
+}
+
+// ---------------------------------------------------------------------------
+// File watcher
+// ---------------------------------------------------------------------------
+
+function setupWatcher(filePath) {
+  if (watcher) watcher.close();
+
+  const files = [filePath];
+  if (path.extname(filePath).toLowerCase() === '.scad') {
+    files.push(...parseScadDependencies(filePath));
+  }
+
+  watcher = chokidar.watch(files, { ignoreInitial: true });
+  watcher.on('change', () => {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => handleFileChange().catch(err => {
+      log(`Watch handler error: ${err.message}`);
+    }), 300);
+  });
+}
+
+async function handleFileChange() {
+  log(`File changed: ${currentFile}`);
+  const ext = path.extname(currentFile).toLowerCase();
+
+  if (ext === '.scad') {
+    const result = await compileScad(currentFile);
+
+    // Re-setup watcher (dependencies may have changed, even on errors)
+    setupWatcher(currentFile);
+
+    if (result.error) {
+      log(`Compilation error: ${result.error}`);
+      broadcast({ type: 'error', message: result.error });
+      return;
+    }
+    currentStlPath = result.stlPath;
+    currentStlBuffer = await fsp.readFile(result.stlPath);
+    lastBoundingBox = parseStlBoundingBox(currentStlBuffer);
+  } else {
+    currentStlBuffer = await fsp.readFile(currentFile);
+    lastBoundingBox = parseStlBoundingBox(currentStlBuffer);
+  }
+
+  broadcast({ type: 'model-updated' });
+}
+
+// ---------------------------------------------------------------------------
+// Open a file (used by both CLI startup and MCP `open` tool)
+// ---------------------------------------------------------------------------
+
+async function openFile(filePath) {
+  const absPath = path.resolve(filePath);
+
+  if (!fs.existsSync(absPath)) {
+    throw new Error(`File not found: ${absPath}`);
+  }
+
+  const ext = path.extname(absPath).toLowerCase();
+  if (ext !== '.scad' && ext !== '.stl') {
+    throw new Error(`Unsupported file type: ${ext}. Only .scad and .stl are supported.`);
+  }
+
+  if (ext === '.scad') {
+    if (!(await checkOpenSCAD())) {
+      throw new Error('OpenSCAD is not installed or not found on $PATH');
+    }
+    const result = await compileScad(absPath);
+    if (result.error) {
+      throw new Error(`OpenSCAD compilation failed:\n${result.error}`);
+    }
+    currentStlPath = result.stlPath;
+    currentStlBuffer = await fsp.readFile(result.stlPath);
+  } else {
+    currentStlPath = absPath;
+    currentStlBuffer = await fsp.readFile(absPath);
+  }
+
+  currentFile = absPath;
+  lastBoundingBox = parseStlBoundingBox(currentStlBuffer);
+  setupWatcher(absPath);
+
+  broadcast({ type: 'model-updated' });
+  broadcast({ type: 'file-info', filename: path.basename(absPath) });
+
+  return {
+    success: true,
+    file: absPath,
+    fileSize: fs.statSync(absPath).size,
+    boundingBox: lastBoundingBox,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Open default browser (cross-platform, no extra dependency)
+// ---------------------------------------------------------------------------
+
+function openBrowser(url) {
+  const { exec } = require('child_process');
+  switch (process.platform) {
+    case 'darwin':  exec(`open "${url}"`);       break;
+    case 'win32':   exec(`start "" "${url}"`);   break;
+    default:        exec(`xdg-open "${url}"`);   break;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    process.stderr.write('Usage: openscad-viewer <file.scad|file.stl>\n');
+    process.exit(1);
+  }
+
+  const filePath = args[0];
+  const ext = path.extname(filePath).toLowerCase();
+
+  if (ext === '.scad' && !(await checkOpenSCAD())) {
+    process.stderr.write(
+      'Error: OpenSCAD is not installed or not found on $PATH.\n' +
+      'Install OpenSCAD to view .scad files, or provide a .stl file instead.\n'
+    );
+    process.exit(1);
+  }
+
+  // ----- Express ----------------------------------------------------------
+  const app = express();
+  const server = http.createServer(app);
+
+  app.use(express.static(path.join(__dirname, 'public')));
+
+  app.get('/model.stl', (_req, res) => {
+    if (!currentStlBuffer) return res.status(404).send('No model loaded');
+    res.set({ 'Content-Type': 'application/octet-stream', 'Cache-Control': 'no-store' });
+    res.send(currentStlBuffer);
+  });
+
+  // ----- WebSocket --------------------------------------------------------
+  const wss = new WebSocketServer({ server });
+
+  wss.on('connection', (ws) => {
+    wsClients.add(ws);
+    log('Browser connected');
+
+    if (currentFile) {
+      ws.send(JSON.stringify({ type: 'file-info', filename: path.basename(currentFile) }));
+      ws.send(JSON.stringify({ type: 'model-updated' }));
+    }
+
+    ws.on('message', (raw) => {
+      try {
+        const msg = JSON.parse(raw);
+        if (msg.requestId && pendingRequests.has(msg.requestId)) {
+          pendingRequests.get(msg.requestId).resolve(msg);
+        }
+      } catch (e) {
+        log('Bad message from browser:', e.message);
+      }
+    });
+
+    ws.on('close', () => { wsClients.delete(ws); log('Browser disconnected'); });
+  });
+
+  // ----- Start HTTP server ------------------------------------------------
+  try {
+    await new Promise((resolve, reject) => {
+      server.on('error', (err) => {
+        reject(err.code === 'EADDRINUSE'
+          ? new Error(`Port ${PORT} is already in use`)
+          : err);
+      });
+      server.listen(PORT, '127.0.0.1', resolve);
+    });
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  log(`Server running at http://localhost:${PORT}`);
+
+  // ----- Open initial file ------------------------------------------------
+  try {
+    await openFile(filePath);
+    log(`Opened: ${currentFile}`);
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  openBrowser(`http://localhost:${PORT}`);
+
+  // ----- MCP server (stdio) ----------------------------------------------
+  const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js');
+  const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
+  const { z } = await import('zod');
+
+  const mcp = new McpServer({ name: 'openscad-viewer', version: '1.0.0' });
+
+  mcp.tool(
+    'open',
+    'Opens a .scad or .stl file in the viewer',
+    { file: z.string().describe('Absolute or relative path to a .scad or .stl file') },
+    async ({ file }) => {
+      try {
+        const result = await openFile(file);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: JSON.stringify({ success: false, error: err.message }) }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  mcp.tool(
+    'view',
+    'Renders the current model at a specified camera angle and returns a screenshot image path',
+    {
+      azimuth:   z.number().min(0).max(360).optional().describe('Horizontal angle in degrees (0-360). Default: 45'),
+      elevation: z.number().min(-90).max(90).optional().describe('Vertical angle in degrees (-90 to 90). Default: 30'),
+      distance:  z.number().optional().describe('Distance from model center. Auto-calculated if omitted.'),
+    },
+    async ({ azimuth, elevation, distance }) => {
+      if (!currentFile) {
+        return {
+          content: [{ type: 'text', text: JSON.stringify({ error: 'No model currently loaded' }) }],
+          isError: true,
+        };
+      }
+
+      azimuth   = azimuth   ?? 45;
+      elevation = elevation ?? 30;
+
+      try {
+        const response = await sendAndWait({
+          type: 'set-camera',
+          azimuth,
+          elevation,
+          distance: distance ?? null,
+        });
+
+        const base64 = response.dataUrl.replace(/^data:image\/png;base64,/, '');
+        const tmpPath = path.join(os.tmpdir(), `openscad-viewer-capture-${Date.now()}.png`);
+        await fsp.writeFile(tmpPath, base64, 'base64');
+
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              imagePath: tmpPath,
+              camera: { azimuth, elevation, distance: response.distance || distance },
+            }, null, 2),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: JSON.stringify({ error: err.message }) }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  const transport = new StdioServerTransport();
+  await mcp.connect(transport);
+  log('MCP server ready on stdio');
+}
+
+main().catch((err) => {
+  process.stderr.write(`Fatal error: ${err.message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "openscad-viewer",
+  "version": "2026.2.1",
+  "description": "Simple openscad model viewer with camera controls.",
+  "main": "index.js",
+  "bin": {
+    "openscad-viewer": "index.js"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fingerskier/openscad-viewer.git"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://github.com/fingerskier/openscad-viewer/issues"
+  },
+  "homepage": "https://github.com/fingerskier/openscad-viewer#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "chokidar": "^3.6.0",
+    "express": "^4.21.0",
+    "ws": "^8.18.0",
+    "zod": "^3.24.0"
+  }
+}

package/public/index.html

@@ -0,0 +1,325 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>OpenSCAD Viewer</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { overflow: hidden; background: #1a1a2e; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
+    #root { width: 100vw; height: 100vh; position: relative; }
+    #canvas-container { width: 100%; height: 100%; }
+    canvas { display: block; }
+
+    .error-overlay {
+      position: fixed;
+      bottom: 20px;
+      left: 20px;
+      right: 20px;
+      max-height: 200px;
+      overflow-y: auto;
+      background: rgba(185, 28, 28, 0.95);
+      color: #fef2f2;
+      padding: 14px 40px 14px 16px;
+      border-radius: 8px;
+      font-family: 'Courier New', Courier, monospace;
+      font-size: 13px;
+      line-height: 1.5;
+      white-space: pre-wrap;
+      word-break: break-word;
+      z-index: 100;
+      box-shadow: 0 4px 24px rgba(0, 0, 0, 0.4);
+    }
+
+    .error-overlay button {
+      position: absolute;
+      top: 8px;
+      right: 10px;
+      background: none;
+      border: none;
+      color: #fef2f2;
+      font-size: 20px;
+      cursor: pointer;
+      opacity: 0.7;
+      line-height: 1;
+    }
+    .error-overlay button:hover { opacity: 1; }
+
+    .loading {
+      position: fixed;
+      top: 50%;
+      left: 50%;
+      transform: translate(-50%, -50%);
+      color: #94a3b8;
+      font-size: 16px;
+    }
+  </style>
+</head>
+<body>
+  <div id="root"></div>
+
+  <!-- React 18 (UMD) -->
+  <script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
+  <script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
+
+  <!-- Three.js import map -->
+  <script type="importmap">
+  {
+    "imports": {
+      "three": "https://unpkg.com/three@0.160.0/build/three.module.js",
+      "three/addons/": "https://unpkg.com/three@0.160.0/examples/jsm/"
+    }
+  }
+  </script>
+
+  <script type="module">
+    import * as THREE from 'three';
+    import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+    import { STLLoader } from 'three/addons/loaders/STLLoader.js';
+
+    const { createElement: h, useState, useEffect, useRef, useCallback } = React;
+
+    // -----------------------------------------------------------------------
+    // Three.js scene (module-level, shared with React via refs/callbacks)
+    // -----------------------------------------------------------------------
+    let renderer, scene, camera, controls, gridHelper;
+    let currentMesh = null;
+    let modelCenter = new THREE.Vector3();
+    let modelSize = 1;
+    const stlLoader = new STLLoader();
+
+    function initScene(container) {
+      renderer = new THREE.WebGLRenderer({ antialias: true, preserveDrawingBuffer: true });
+      renderer.setSize(window.innerWidth, window.innerHeight);
+      renderer.setPixelRatio(window.devicePixelRatio);
+      renderer.setClearColor(0x1a1a2e);
+      container.appendChild(renderer.domElement);
+
+      scene = new THREE.Scene();
+
+      camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 0.1, 100000);
+
+      // Lights
+      scene.add(new THREE.AmbientLight(0x404040, 2));
+      const light1 = new THREE.DirectionalLight(0xffffff, 1.5);
+      light1.position.set(1, 1, 1);
+      scene.add(light1);
+      const light2 = new THREE.DirectionalLight(0xffffff, 0.8);
+      light2.position.set(-1, -0.5, -1);
+      scene.add(light2);
+
+      // Controls
+      controls = new OrbitControls(camera, renderer.domElement);
+      controls.enableDamping = true;
+      controls.dampingFactor = 0.05;
+
+      // Grid
+      gridHelper = new THREE.GridHelper(100, 20, 0x444466, 0x333355);
+      scene.add(gridHelper);
+
+      // Render loop
+      (function animate() {
+        requestAnimationFrame(animate);
+        controls.update();
+        renderer.render(scene, camera);
+      })();
+
+      // Resize handler
+      window.addEventListener('resize', () => {
+        camera.aspect = window.innerWidth / window.innerHeight;
+        camera.updateProjectionMatrix();
+        renderer.setSize(window.innerWidth, window.innerHeight);
+      });
+    }
+
+    function loadModel(onDone) {
+      fetch('/model.stl', { cache: 'no-store' })
+        .then((r) => { if (!r.ok) throw new Error('No model'); return r.arrayBuffer(); })
+        .then((buf) => {
+          const geometry = stlLoader.parse(buf);
+          geometry.computeBoundingBox();
+          geometry.computeVertexNormals();
+
+          if (currentMesh) {
+            scene.remove(currentMesh);
+            currentMesh.geometry.dispose();
+            currentMesh.material.dispose();
+          }
+
+          const material = new THREE.MeshPhongMaterial({
+            color: 0x4a90d9,
+            specular: 0x222222,
+            shininess: 40,
+          });
+          currentMesh = new THREE.Mesh(geometry, material);
+          scene.add(currentMesh);
+
+          // Bounding box metrics
+          const bbox = geometry.boundingBox;
+          modelCenter = new THREE.Vector3();
+          bbox.getCenter(modelCenter);
+          const size = new THREE.Vector3();
+          bbox.getSize(size);
+          modelSize = Math.max(size.x, size.y, size.z);
+
+          // Scale grid to model
+          const gridScale = Math.max(1, modelSize / 20);
+          gridHelper.scale.setScalar(gridScale);
+
+          // Default isometric camera: azimuth 45°, elevation 30°
+          setCameraSpherical(45, 30, modelSize * 2.5, false);
+
+          if (onDone) onDone();
+        })
+        .catch((err) => console.error('Model load failed:', err));
+    }
+
+    function setCameraSpherical(azimuthDeg, elevationDeg, dist, animate = true) {
+      const distance = dist || modelSize * 2.5;
+      const az = (azimuthDeg * Math.PI) / 180;
+      const el = (elevationDeg * Math.PI) / 180;
+
+      const target = new THREE.Vector3(
+        modelCenter.x + distance * Math.cos(el) * Math.sin(az),
+        modelCenter.y + distance * Math.sin(el),
+        modelCenter.z + distance * Math.cos(el) * Math.cos(az),
+      );
+
+      if (!animate) {
+        camera.position.copy(target);
+        camera.lookAt(modelCenter);
+        controls.target.copy(modelCenter);
+        controls.update();
+        return Promise.resolve(distance);
+      }
+
+      // Smooth animation
+      return new Promise((resolve) => {
+        const start = camera.position.clone();
+        const t0 = performance.now();
+        const dur = 600;
+
+        function step(now) {
+          const p = Math.min((now - t0) / dur, 1);
+          const ease = p < 0.5 ? 2 * p * p : 1 - Math.pow(-2 * p + 2, 2) / 2;
+          camera.position.lerpVectors(start, target, ease);
+          camera.lookAt(modelCenter);
+          controls.target.copy(modelCenter);
+          controls.update();
+          if (p < 1) {
+            requestAnimationFrame(step);
+          } else {
+            camera.position.copy(target);
+            camera.lookAt(modelCenter);
+            controls.update();
+            // Extra frame to ensure render is up to date
+            requestAnimationFrame(() => {
+              renderer.render(scene, camera);
+              resolve(distance);
+            });
+          }
+        }
+        requestAnimationFrame(step);
+      });
+    }
+
+    function captureScreenshot() {
+      renderer.render(scene, camera);
+      return renderer.domElement.toDataURL('image/png');
+    }
+
+    // -----------------------------------------------------------------------
+    // React App
+    // -----------------------------------------------------------------------
+    function App() {
+      const containerRef = useRef(null);
+      const wsRef = useRef(null);
+      const [error, setError] = useState(null);
+      const [loading, setLoading] = useState(true);
+
+      // Initialise Three.js scene once
+      useEffect(() => {
+        if (containerRef.current && !renderer) {
+          initScene(containerRef.current);
+        }
+      }, []);
+
+      // WebSocket connection
+      useEffect(() => {
+        let ws;
+        let reconnectTimer;
+
+        function connect() {
+          ws = new WebSocket(`ws://${window.location.host}`);
+          wsRef.current = ws;
+
+          ws.onmessage = async (event) => {
+            const msg = JSON.parse(event.data);
+
+            switch (msg.type) {
+              case 'model-updated':
+                loadModel(() => {
+                  setLoading(false);
+                  setError(null);
+                });
+                break;
+
+              case 'file-info':
+                document.title = msg.filename + ' \u2014 OpenSCAD Viewer';
+                break;
+
+              case 'error':
+                setError(msg.message);
+                break;
+
+              case 'set-camera': {
+                const dist = await setCameraSpherical(
+                  msg.azimuth,
+                  msg.elevation,
+                  msg.distance,
+                  true,
+                );
+                const dataUrl = captureScreenshot();
+                ws.send(JSON.stringify({
+                  requestId: msg.requestId,
+                  type: 'screenshot',
+                  dataUrl,
+                  distance: dist,
+                }));
+                break;
+              }
+            }
+          };
+
+          ws.onclose = () => {
+            reconnectTimer = setTimeout(connect, 2000);
+          };
+
+          ws.onerror = () => ws.close();
+        }
+
+        connect();
+
+        return () => {
+          clearTimeout(reconnectTimer);
+          if (ws) ws.close();
+        };
+      }, []);
+
+      return h('div', { style: { width: '100vw', height: '100vh', position: 'relative' } },
+        h('div', { ref: containerRef, id: 'canvas-container' }),
+
+        loading && h('div', { className: 'loading' }, 'Loading model\u2026'),
+
+        error && h('div', { className: 'error-overlay' },
+          h('button', { onClick: () => setError(null) }, '\u00D7'),
+          error,
+        ),
+      );
+    }
+
+    // Mount
+    ReactDOM.createRoot(document.getElementById('root')).render(h(App));
+  </script>
+</body>
+</html>

package/samples/example.scad

@@ -0,0 +1,23 @@
+// Example OpenSCAD file — a rounded cube with cylindrical holes
+// Run: npx openscad-viewer samples/example.scad
+
+$fn = 32;
+
+difference() {
+    // Rounded base block
+    minkowski() {
+        cube([20, 20, 10], center = true);
+        sphere(r = 2);
+    }
+
+    // Hole through the top
+    cylinder(h = 20, r = 4, center = true);
+
+    // Hole through the front
+    rotate([90, 0, 0])
+        cylinder(h = 30, r = 3, center = true);
+
+    // Hole through the side
+    rotate([0, 90, 0])
+        cylinder(h = 30, r = 3, center = true);
+}

package/samples/example.stl

@@ -0,0 +1,114 @@
+solid example
+  facet normal 0 0 -1
+    outer loop
+      vertex 0 0 0
+      vertex 10 0 0
+      vertex 10 10 0
+    endloop
+  endfacet
+  facet normal 0 0 -1
+    outer loop
+      vertex 0 0 0
+      vertex 10 10 0
+      vertex 0 10 0
+    endloop
+  endfacet
+  facet normal 0 0 1
+    outer loop
+      vertex 0 0 8
+      vertex 10 10 8
+      vertex 10 0 8
+    endloop
+  endfacet
+  facet normal 0 0 1
+    outer loop
+      vertex 0 0 8
+      vertex 0 10 8
+      vertex 10 10 8
+    endloop
+  endfacet
+  facet normal 0 -1 0
+    outer loop
+      vertex 0 0 0
+      vertex 10 0 8
+      vertex 10 0 0
+    endloop
+  endfacet
+  facet normal 0 -1 0
+    outer loop
+      vertex 0 0 0
+      vertex 0 0 8
+      vertex 10 0 8
+    endloop
+  endfacet
+  facet normal 0 1 0
+    outer loop
+      vertex 0 10 0
+      vertex 10 10 0
+      vertex 10 10 8
+    endloop
+  endfacet
+  facet normal 0 1 0
+    outer loop
+      vertex 0 10 0
+      vertex 10 10 8
+      vertex 0 10 8
+    endloop
+  endfacet
+  facet normal -1 0 0
+    outer loop
+      vertex 0 0 0
+      vertex 0 10 0
+      vertex 0 10 8
+    endloop
+  endfacet
+  facet normal -1 0 0
+    outer loop
+      vertex 0 0 0
+      vertex 0 10 8
+      vertex 0 0 8
+    endloop
+  endfacet
+  facet normal 1 0 0
+    outer loop
+      vertex 10 0 0
+      vertex 10 0 8
+      vertex 10 10 8
+    endloop
+  endfacet
+  facet normal 1 0 0
+    outer loop
+      vertex 10 0 0
+      vertex 10 10 8
+      vertex 10 10 0
+    endloop
+  endfacet
+  facet normal 0 -0.5547 0.83205
+    outer loop
+      vertex 0 0 8
+      vertex 5 5 12
+      vertex 10 0 8
+    endloop
+  endfacet
+  facet normal 0 0.5547 0.83205
+    outer loop
+      vertex 10 10 8
+      vertex 5 5 12
+      vertex 0 10 8
+    endloop
+  endfacet
+  facet normal -0.8575 0 0.5145
+    outer loop
+      vertex 0 0 8
+      vertex 0 10 8
+      vertex 5 5 12
+    endloop
+  endfacet
+  facet normal 0.8575 0 0.5145
+    outer loop
+      vertex 10 0 8
+      vertex 5 5 12
+      vertex 10 10 8
+    endloop
+  endfacet
+endsolid example

package/spec/openscad-viewer.md

@@ -0,0 +1,155 @@
+# openscad-viewer Specification
+
+A browser-based OpenSCAD model viewer with MCP tool integration, enabling AI agents to open and inspect 3D models while the user watches in real-time.
+
+## Prerequisites
+
+- **OpenSCAD** must be installed locally and available on `$PATH`. The application checks for this at startup and fails with a clear error message if not found. (Only required for `.scad` files — `.stl` files can be viewed without OpenSCAD.)
+- **Node.js**
+
+## Rendering Pipeline
+
+**For `.scad` files:**
+```
+.scad file → OpenSCAD CLI → .stl (temp) → serve to browser → Three.js renders in 3D
+```
+
+1. Server receives a `.scad` file path
+2. Server invokes `openscad -o /tmp/output.stl input.scad` to compile
+3. Server serves the resulting STL to the browser via HTTP/WebSocket
+4. Browser renders the STL using Three.js with orbit camera controls
+
+**For `.stl` files:**
+```
+.stl file → serve directly to browser → Three.js renders in 3D
+```
+
+1. Server receives a `.stl` file path
+2. Server serves the STL directly to the browser (no compilation)
+3. Browser renders using Three.js — same viewer, same controls
+
+## CLI
+
+```
+npx openscad-viewer <file.scad|file.stl>
+```
+
+- **File argument is required** — errors if not provided
+- **Fixed port**: `8439` — fails if the port is already in use
+- **Auto-opens** the default browser to `http://localhost:8439`
+- Puts the filename in the browser title bar
+
+## Browser UI
+
+### 3D Viewport
+
+- Three.js renderer displaying the compiled STL model
+- Orbit-style camera controls: rotate, pan, zoom (OrbitControls)
+- Default camera position: isometric view at a reasonable distance from the model bounding box
+
+### Error Display
+
+- On `.scad` compilation error: **keep the last successfully rendered model visible** and **overlay the OpenSCAD error message** (toast/banner) so the user sees both the last good state and what went wrong
+
+### Title Bar
+
+- Shows the opened file name
+
+## MCP Tools (stdio transport)
+
+The viewer process itself is the MCP server, communicating via stdin/stdout.
+
+### `open`
+
+Opens a `.scad` file in the viewer.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `file` | string | yes | Absolute or relative path to a `.scad` or `.stl` file |
+
+**Returns:**
+
+```json
+{
+  "success": true,
+  "file": "/absolute/path/to/model.scad",
+  "fileSize": 2048,
+  "boundingBox": { "min": [-10, -10, 0], "max": [10, 10, 20] }
+}
+```
+
+**Errors:**
+
+- File not found
+- Unsupported file type (not `.scad` or `.stl`)
+- OpenSCAD compilation failure (include the stderr output) — `.scad` only
+
+### `view`
+
+Renders the current model at a specified camera angle and returns an image.
+
+**Parameters:**
+
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `azimuth` | number | no | 45 | Horizontal angle in degrees (0-360) |
+| `elevation` | number | no | 30 | Vertical angle in degrees (-90 to 90) |
+| `distance` | number | no | auto | Distance from model center. Auto-calculated from bounding box if omitted. |
+
+**Returns:**
+
+```json
+{
+  "imagePath": "/tmp/openscad-viewer-capture-xxxxx.png",
+  "camera": { "azimuth": 45, "elevation": 30, "distance": 100 }
+}
+```
+
+The image is a PNG screenshot of the Three.js viewport at the requested angle.
+
+**Side effect:** The browser camera **animates smoothly** to the requested position, so the user sees what the agent is looking at.
+
+**Errors:**
+
+- No model currently loaded
+
+## Real-Time Communication
+
+**WebSocket** connection between server and browser for:
+
+1. **Model updates**: When the STL is recompiled (due to file change or new `open`), push the new geometry to the browser
+2. **Camera sync**: When an agent calls `view`, push the target camera position to the browser, which animates to it
+3. **Error notifications**: Push compilation errors to the browser for overlay display
+
+## File Watching
+
+- Watch the opened file for changes
+- **For `.scad` files**, also watch `include`/`use` dependencies — parse for `include <...>` and `use <...>` statements and watch those files too
+- On any watched file change:
+  - **`.scad`**: Re-run OpenSCAD CLI compilation. If successful, push new STL to browser. If error, push error message (keep last good model).
+  - **`.stl`**: Re-serve the updated file directly to the browser.
+- Debounce rapid changes (300ms) to avoid excessive recompilation
+
+## Architecture
+
+```
+Node.js + Express + React
+
+┌─────────────┐    stdio   ┌──────────────────┐   WebSocket   ┌─────────────┐
+│   AI Agent  │◄──────────►│  Node.js Server  │◄─────────────►│   Browser   │
+│ (MCP client)│            │  (Express + MCP) │               │  (React +   │
+└─────────────┘            │                  │   HTTP/GET    │   Three.js) │
+                           │  - file watcher   │──────────────►│             │
+                           │  - OpenSCAD CLI  │   (STL files)  └─────────────┘
+                           └──────────────────┘
+```
+
+## Scope Boundaries (Explicitly Out of Scope)
+
+- Multiple simultaneous model files (one at a time only)
+- Formats beyond `.scad` and `.stl` (no OBJ, 3MF, etc.)
+- OpenSCAD customizer variable editing
+- Lighting or material controls in the UI
+- Remote/network access (localhost only)