geometryview 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# GeometryView
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**See inside your CAD models, fast.** Open STEP and STL files in your browser, and let your AI apps
+open, inspect and picture them.
+
+<img src="https://raw.githubusercontent.com/atharvaaalok/geometryview/main/Docs/media/styles.jpg" alt="A drive cut open, in six drawing styles" width="600">
+
+## View a model
+
+```sh
+npx geometryview part.step     # opens it in your browser
+npx geometryview               # the viewer, with your folders and recent files
+```
+
+The viewer is served from your computer only (127.0.0.1), and your files never leave it. It needs a
+browser with WebGPU: Chrome or Edge, or Safari 26 or later. Or use the hosted copy, with sample
+models: [atharvaaalok.github.io/geometryview](https://atharvaaalok.github.io/geometryview/).
+
+## Use it from your AI app
+
+`geometryview --mcp` is a tool server (MCP) with four tools:
+
+- `open_model` opens a file and sums it up.
+- `get_structure` lists its assemblies and parts.
+- `render_view` returns a picture: any view, any of six styles, sections, parts alone.
+- `open_in_viewer` shows it to you, live.
+
+```sh
+claude mcp add geometryview -- npx -y geometryview --mcp     # Claude Code
+codex mcp add geometryview -- npx -y geometryview --mcp      # Codex
+```
+
+Other apps take the same command, `npx -y geometryview --mcp`, in their MCP settings. Claude
+Desktop can also install it in one click from the `.mcpb` in the
+[latest release](https://github.com/atharvaaalok/geometryview/releases/latest).
+
+More, including the Mac app and the iPhone: [github.com/atharvaaalok/geometryview](https://github.com/atharvaaalok/geometryview).
+MIT licensed.

package/bin/geometryview.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// geometryview [file]      serves the viewer on this machine and opens it in the browser, with the
+//                          file if one is given
+// geometryview --no-open [file]
+//                          serves it and prints its address, to open in any browser, such as an
+//                          AI app's own; the file opens in the first page to load it
+// geometryview --mcp       runs the tool server that AI apps start (Claude, Codex, ChatGPT)
+//
+// The viewer is at http://127.0.0.1:47700, so the browser keeps its library from one run to the
+// next. If GeometryView is already running there, the browser is opened at it. --port N, or
+// GEOMETRYVIEW_PORT, chooses another port.
+
+import { serve } from "../src/mcp.mjs";
+import { linkToPage, openBrowser, openInPage, preferredPort, viewerServer } from "../src/page.mjs";
+import { instructions, tools } from "../src/tools.mjs";
+import { viewerAt } from "../src/web.mjs";
+
+const args = process.argv.slice(2);
+const at = args.indexOf("--port");
+if (at >= 0) {
+  process.env.GEOMETRYVIEW_PORT = args[at + 1];
+  args.splice(at, 2);
+}
+
+if (args.includes("--mcp")) {
+  serve(tools, instructions);
+} else if (args.includes("--help") || args.includes("-h")) {
+  process.stdout.write("usage: geometryview [--port N] [--no-open] [file] | --mcp\n");
+} else {
+  const file = args.find((arg) => !arg.startsWith("-"));
+  const launch = !args.includes("--no-open") && !args.includes("--serve");
+  const port = preferredPort();
+  if (port !== 0 && (await viewerAt(port))) {
+    const address = `http://127.0.0.1:${port}/`;
+    process.stdout.write(`GeometryView is already running at ${address}\n`);
+    if (file) {
+      process.stdout.write("Open the file there, by dragging it onto the page or with ⌘O, or stop " +
+                           "that viewer and run this again.\n");
+    }
+    if (launch) await openBrowser(address);
+  } else if (!launch) {
+    const viewer = await viewerServer();
+    process.stdout.write(`GeometryView is at ${viewer.url}\nOpen that address in a browser. ` +
+                         "Press Ctrl-C to stop.\n");
+    if (file) {
+      try {
+        await linkToPage(file);
+      } catch (error) {
+        process.stderr.write(`${error.message}\n`);
+      }
+    }
+  } else {
+    const viewer = await viewerServer();
+    process.stdout.write(`GeometryView is at ${viewer.address}/\nPress Ctrl-C to stop.\n`);
+    if (file) {
+      try {
+        await openInPage(file);
+      } catch (error) {
+        process.stderr.write(`${error.message}\n`);
+      }
+    } else {
+      await openBrowser(viewer.url);
+    }
+  }
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "geometryview",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "View STEP and STL models in your browser, and let AI apps open, inspect and picture them (MCP).",
+  "keywords": [
+    "step",
+    "stl",
+    "cad",
+    "3d",
+    "viewer",
+    "webgpu",
+    "wasm",
+    "opencascade",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "homepage": "https://github.com/atharvaaalok/geometryview#readme",
+  "bugs": {
+    "url": "https://github.com/atharvaaalok/geometryview/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/atharvaaalok/geometryview.git",
+    "directory": "Launcher"
+  },
+  "license": "MIT",
+  "author": "Atharva Aalok",
+  "type": "module",
+  "bin": {
+    "geometryview": "bin/geometryview.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "web"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "prepack": "node scripts/web.mjs"
+  }
+}

package/src/bridge.mjs

@@ -0,0 +1,77 @@
+// The bridge between the launcher and the viewer's pages: requests from the AI app's tools to the
+// most recently connected page, and the page's answers. Messages are JSON:
+//   launcher to page:  { id, method, params }
+//   page to launcher:  { id, result } or { id, error }
+
+export class Bridge {
+  #pages = [];
+  #pending = new Map();
+  #next = 1;
+  #waiting = [];
+
+  /// Takes a page's connection, from acceptWebSocket.
+  attach(connection) {
+    this.#pages.push(connection);
+    connection.onmessage = (text) => {
+      let message;
+      try {
+        message = JSON.parse(text);
+      } catch {
+        return;
+      }
+      const pending = this.#pending.get(message.id);
+      if (!pending) return;
+      this.#pending.delete(message.id);
+      clearTimeout(pending.timer);
+      if (message.error !== undefined) pending.reject(new Error(String(message.error)));
+      else pending.resolve(message.result);
+    };
+    connection.onclose = () => {
+      this.#pages = this.#pages.filter((page) => page !== connection);
+      for (const [id, pending] of this.#pending) {
+        if (pending.page === connection) {
+          this.#pending.delete(id);
+          clearTimeout(pending.timer);
+          pending.reject(new Error("The viewer's page was closed."));
+        }
+      }
+    };
+    for (const resolve of this.#waiting.splice(0)) resolve(connection);
+  }
+
+  get connected() { return this.#pages.length > 0; }
+
+  /// The newest page, waiting up to `timeoutMs` for one to connect.
+  page(timeoutMs) {
+    if (this.connected) return Promise.resolve(this.#pages.at(-1));
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#waiting = this.#waiting.filter((w) => w !== done);
+        reject(new Error("The viewer did not open in a browser in time."));
+      }, timeoutMs);
+      const done = (page) => {
+        clearTimeout(timer);
+        resolve(page);
+      };
+      this.#waiting.push(done);
+    });
+  }
+
+  /// Asks the newest page to do `method`, and returns its result.
+  async request(method, params = {}, { timeoutMs = 120_000, waitMs = 30_000 } = {}) {
+    const page = await this.page(waitMs);
+    const id = this.#next++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(id);
+        reject(new Error(`The viewer did not answer ${method} in time.`));
+      }, timeoutMs);
+      this.#pending.set(id, { resolve, reject, timer, page });
+      page.send(JSON.stringify({ id, method, params }));
+    });
+  }
+
+  close() {
+    for (const page of this.#pages) page.close();
+  }
+}

package/src/mcp.mjs

@@ -0,0 +1,73 @@
+// The Model Context Protocol over standard input and output: newline-delimited JSON-RPC 2.0.
+// Only what a tool server needs: initialize, ping, tools/list and tools/call. Standard output
+// carries the protocol alone, so anything else goes to standard error.
+
+import { createInterface } from "node:readline";
+
+const SERVER = { name: "geometryview", version: "0.1.0" };
+const LATEST_PROTOCOL = "2025-06-18";
+
+/// Serves `tools` until standard input closes. Each tool is { name, description, inputSchema,
+/// call(args) -> Promise<content[]> }; a thrown error becomes a tool error the model can read.
+export function serve(tools, instructions) {
+  const byName = new Map(tools.map((tool) => [tool.name, tool]));
+  const reply = (id, result) => send({ jsonrpc: "2.0", id, result });
+  const fail = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } });
+
+  const handlers = {
+    initialize: (params) => ({
+      // Answer in the client's version: every version so far shares what this server uses.
+      protocolVersion: params?.protocolVersion ?? LATEST_PROTOCOL,
+      capabilities: { tools: {} },
+      serverInfo: SERVER,
+      instructions,
+    }),
+    ping: () => ({}),
+    "tools/list": () => ({
+      tools: tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+    }),
+    "tools/call": async (params) => {
+      const tool = byName.get(params?.name);
+      if (!tool) {
+        return { content: [{ type: "text", text: `There is no tool named ${params?.name}.` }],
+                 isError: true };
+      }
+      try {
+        return { content: await tool.call(params.arguments ?? {}) };
+      } catch (error) {
+        return { content: [{ type: "text", text: error.message ?? String(error) }], isError: true };
+      }
+    },
+  };
+
+  const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+  lines.on("line", async (line) => {
+    if (!line.trim()) {
+      return;
+    }
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      fail(null, -32700, "Parse error");
+      return;
+    }
+    const handler = handlers[message.method];
+    if (message.id === undefined) {
+      return; // a notification, such as notifications/initialized
+    }
+    if (!handler) {
+      fail(message.id, -32601, `Method not found: ${message.method}`);
+      return;
+    }
+    try {
+      reply(message.id, await handler(message.params));
+    } catch (error) {
+      fail(message.id, -32603, error.message ?? String(error));
+    }
+  });
+}
+
+function send(message) {
+  process.stdout.write(JSON.stringify(message) + "\n");
+}

package/src/native.mjs

@@ -0,0 +1,176 @@
+// The native engine on a Mac, driven through gcli: import a STEP or STL file into a cache file,
+// read its assembly tree and statistics, and render it to a PNG. The universal WebAssembly engine
+// will take this module's place on other machines.
+
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+const here = dirname(fileURLToPath(import.meta.url));
+
+/// Where gcli, the OCCT worker and the shader library are: GEOMETRYVIEW_NATIVE_DIR if set, else the
+/// copy bundled beside this package, else the repository's release build.
+function nativeDirectory() {
+  const candidates = [
+    process.env.GEOMETRYVIEW_NATIVE_DIR,
+    join(here, "../native"),
+    join(here, "../../build/release"),
+  ].filter(Boolean);
+  for (const directory of candidates) {
+    if (existsSync(join(directory, "gcli")) || existsSync(join(directory, "Tools/gcli"))) {
+      return directory;
+    }
+  }
+  throw new Error("The native engine was not found. Build it with `cmake --build --preset " +
+                  "release`, or set GEOMETRYVIEW_NATIVE_DIR.");
+}
+
+/// Whether this machine has the native engine (a Mac with gcli built or bundled), unless
+/// GEOMETRYVIEW_ENGINE=page asks for the browser's.
+export function nativeAvailable() {
+  if (process.env.GEOMETRYVIEW_ENGINE === "page") return false;
+  try {
+    nativeDirectory();
+    return process.platform === "darwin";
+  } catch {
+    return false;
+  }
+}
+
+function binaries() {
+  const directory = nativeDirectory();
+  // A bundled copy is flat; a build directory keeps each target in its own folder.
+  const flat = existsSync(join(directory, "gcli"));
+  return {
+    gcli: join(directory, flat ? "gcli" : "Tools/gcli"),
+    worker: join(directory, flat ? "geometryview-occt-worker" : "Import/geometryview-occt-worker"),
+    shaders: join(directory, flat ? "default.metallib" : "shaders/default.metallib"),
+  };
+}
+
+const cacheDirectory = join(homedir(), "Library/Caches/geometryview");
+
+/// Imports `path` unless an import of the same file, unchanged, is cached. Returns the cache file.
+// The cache file version gcli writes and reads, from Import/format/blob.h.
+export const kCacheVersion = 5;
+
+// Whether a cache file is in the current format: 8 bytes of magic, then a little-endian u32.
+async function isCurrent(path) {
+  const file = await open(path, "r");
+  try {
+    const header = Buffer.alloc(12);
+    const { bytesRead } = await file.read(header, 0, 12, 0);
+    return bytesRead === 12 && header.readUInt32LE(8) === kCacheVersion;
+  } finally {
+    await file.close();
+  }
+}
+
+export async function importModel(path) {
+  const source = resolve(path);
+  const info = await stat(source).catch(() => {
+    throw new Error(`There is no file at ${source}.`);
+  });
+  if (!info.isFile()) {
+    throw new Error(`${source} is not a file.`);
+  }
+  if (!/\.(step|stp|stl)$/i.test(source)) {
+    throw new Error("Only STEP (.step, .stp) and STL (.stl) files can be opened.");
+  }
+  const key = createHash("sha256")
+    .update(`${source}\0${info.size}\0${info.mtimeMs}`)
+    .digest("hex")
+    .slice(0, 32);
+  const blob = join(cacheDirectory, `${key}.geoblob`);
+  if (existsSync(blob)) {
+    // One in an older format is made again: gcli reads only its own.
+    if (await isCurrent(blob)) return { blob, source, fromCache: true };
+    await rm(blob, { force: true });
+  }
+  await mkdir(cacheDirectory, { recursive: true });
+  const { gcli, worker } = binaries();
+  const partial = `${blob}.${process.pid}.partial`;
+  try {
+    await run(gcli, ["import", source, partial, worker], { maxBuffer: 1 << 20 });
+  } catch (error) {
+    await rm(partial, { force: true });
+    throw new Error(`Could not import ${basename(source)}: ${(error.stderr || error.message).trim()}`);
+  }
+  await rename(partial, blob);
+  return { blob, source, fromCache: false };
+}
+
+/// The assembly tree: one node per entry, depth-first, with parent, kind, name and body range.
+export async function readTree(blob) {
+  const { gcli } = binaries();
+  const { stdout } = await run(gcli, ["tree", blob], { maxBuffer: 1 << 30 });
+  return JSON.parse(stdout);
+}
+
+/// Faces, triangles, area, signed volume and the bounding box.
+export async function readStats(blob) {
+  const { gcli } = binaries();
+  const { stdout } = await run(gcli, ["stats", blob], { maxBuffer: 1 << 20 });
+  return JSON.parse(stdout);
+}
+
+/// Renders the cache file and returns the PNG's bytes.
+export async function render(blob, view) {
+  const { gcli, shaders } = binaries();
+  const png = join(tmpdir(), `geometry-view-${process.pid}-${Date.now()}.png`);
+  const args = [
+    "render", shaders, blob, png,
+    String(view.width), String(view.height),
+    String(view.azimuth), String(view.elevation),
+    view.perspective ? "perspective" : "ortho",
+    String(view.style), String(view.colour),
+    view.section ?? "",
+    view.overlay ? "overlay" : "plain",
+    (view.isolate ?? []).join(","),
+  ];
+  try {
+    await run(gcli, args, { maxBuffer: 1 << 20 });
+    return await readFile(png);
+  } catch (error) {
+    throw new Error((error.stderr || error.message).trim());
+  } finally {
+    await rm(png, { force: true });
+  }
+}
+
+/// The native GeometryView app, if it is installed or built.
+export function viewerApplication() {
+  const candidates = [
+    process.env.GEOMETRYVIEW_APP,
+    "/Applications/GeometryView.app",
+    join(homedir(), "Applications/GeometryView.app"),
+    join(here, "../../build/release/App/GeometryView.app"),
+  ].filter(Boolean);
+  return candidates.find((candidate) => existsSync(candidate)) ?? null;
+}
+
+/// Opens `path` in the app, then, if asked, shows some parts alone, in a style and colours: a
+/// geometryview://show request sent after the file, which the app applies once the model is in.
+/// The file itself goes the usual way, which grants the app's sandbox access to it.
+export async function openInViewer(path, { isolate = [], style, colour } = {}) {
+  const application = viewerApplication();
+  if (!application) {
+    throw new Error("The GeometryView app was not found on this Mac.");
+  }
+  const file = resolve(path);
+  await run("open", ["-a", application, file]);
+  if (isolate.length > 0 || style || colour) {
+    const query = new URLSearchParams({ file });
+    for (const name of isolate) query.append("isolate", name);
+    if (style) query.set("style", style);
+    if (colour) query.set("colour", colour);
+    await run("open", ["-a", application, `geometryview://show?${query}`]);
+  }
+  return application;
+}

package/src/page.mjs

@@ -0,0 +1,147 @@
+// The viewer in the person's browser, as an engine for the AI app's tools: on machines without the
+// native engine, a model is opened, described and pictured by the page, which the person sees too.
+
+import { execFile, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { kDefaultPort, startViewer } from "./web.mjs";
+
+let viewer = null;
+let shownFor = null; // the path the page has open, as the launcher asked
+
+/// The port asked for: GEOMETRYVIEW_PORT, or the usual one.
+export function preferredPort() {
+  return Number(process.env.GEOMETRYVIEW_PORT ?? kDefaultPort);
+}
+
+/// The viewer's server, started once per launcher, on the preferred port. If something else holds
+/// it, such as another launcher, on any free port: a page there has a library of its own.
+export async function viewerServer() {
+  if (!viewer) {
+    const port = preferredPort();
+    try {
+      viewer = await startViewer({ port });
+    } catch (error) {
+      if (error.code !== "EADDRINUSE" || port === 0) throw error;
+      viewer = await startViewer({ port: 0 });
+      process.stderr.write(`Port ${port} is in use, so the viewer is at ${viewer.address}, where ` +
+                           "the browser keeps a library of its own.\n");
+    }
+  }
+  return viewer;
+}
+
+// Chrome on Linux gives a page WebGPU only with Vulkan on, which is off by default on NVIDIA
+// GPUs at least, and flags cannot reach a Chrome already running. So on Linux the viewer opens in a
+// Chrome window of its own, with its own profile, and Vulkan on.
+const linuxChromes = ["/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/usr/bin/chromium",
+                      "/usr/bin/chromium-browser", "/snap/bin/chromium"];
+
+/// The arguments that open `url` in the viewer's own Chrome window on Linux, or null without Chrome.
+export function linuxViewerWindow(url, home = homedir(), exists = existsSync) {
+  const chrome = process.env.GEOMETRYVIEW_CHROME ?? linuxChromes.find((path) => exists(path));
+  if (!chrome) return null;
+  const state = process.env.XDG_STATE_HOME ?? join(home, ".local/state");
+  return [chrome, [`--user-data-dir=${join(state, "geometryview/chrome")}`, "--enable-features=Vulkan",
+                   "--no-first-run", "--no-default-browser-check", `--app=${url}`]];
+}
+
+/// Opens `url` in the person's default browser, or on Linux the viewer's own Chrome window.
+export function openBrowser(url) {
+  const window = process.platform === "linux" ? linuxViewerWindow(url) : null;
+  if (window) {
+    // It outlives the launcher's request: the person keeps the window.
+    spawn(window[0], window[1], { detached: true, stdio: "ignore" }).unref();
+    return Promise.resolve();
+  }
+  const [command, args] =
+    process.platform === "darwin" ? ["open", [url]]
+    : process.platform === "win32" ? ["cmd", ["/c", "start", "", url.replace(/&/g, "^&")]]
+    : ["xdg-open", [url]];
+  return new Promise((done) => execFile(command, args, () => done()));
+}
+
+/// The page. If none is connected, the browser is opened at it, unless `launch` is false: then
+/// the first page to connect from the viewer's address, opened anywhere, such as an AI app's own
+/// browser pane.
+async function page({ launch = true } = {}) {
+  const server = await viewerServer();
+  if (!server.bridge.connected) {
+    shownFor = null;
+    if (launch) await openBrowser(server.url);
+  }
+  return server;
+}
+
+/// The model file at `path`, checked: its full path and modification time.
+async function modelFile(path) {
+  const source = resolve(path);
+  const info = await stat(source).catch(() => {
+    throw new Error(`There is no file at ${source}.`);
+  });
+  if (!info.isFile()) throw new Error(`${source} is not a file.`);
+  if (!/\.(step|stp|stl|geoblob)$/i.test(source)) {
+    throw new Error("Only STEP (.step, .stp) and STL (.stl) files can be opened.");
+  }
+  return { source, info };
+}
+
+/// Opens `path` in the page, unless it is open there already. Returns the scene's description.
+/// `waitMs` is how long to wait for a page to connect.
+export async function openInPage(path, { launch = true, waitMs = 30_000 } = {}) {
+  const { source, info } = await modelFile(path);
+  const server = await page({ launch });
+  if (shownFor === source && server.bridge.connected) {
+    return server.bridge.request("describe", {}, { waitMs });
+  }
+  const description = await server.bridge.request("open", {
+    url: server.grant(source), name: basename(source), lastModified: info.mtimeMs,
+  }, { timeoutMs: 600_000, waitMs });
+  shownFor = source;
+  return description;
+}
+
+/// Opens `path` in the page and shows it as asked: `isolate`, names of parts to show alone, and a
+/// `style` and `colour`, as the look card numbers them. Returns the scene's description, with
+/// `isolated`, how many parts and assemblies are shown alone, when some were asked for.
+export async function showInPage(path, show = {}, options = {}) {
+  const description = await openInPage(path, options);
+  if (show.isolate?.length > 0 || show.style !== undefined || show.colour !== undefined) {
+    return (await viewerServer()).bridge.request("show", show, { waitMs: options.waitMs });
+  }
+  return description;
+}
+
+// How long a link waits for its page: the person may open it a while after it is offered.
+const kLinkWaitMs = 30 * 60_000;
+
+/// The viewer's address for an AI app to open in its own browser, with `path` shown in it as
+/// asked: at once in a page already connected, or else in the first page to connect. Opens no
+/// browser itself.
+export async function linkToPage(path, show = {}) {
+  await modelFile(path);
+  const server = await viewerServer();
+  const connected = server.bridge.connected;
+  const showing = showInPage(path, show, { launch: false, waitMs: kLinkWaitMs });
+  if (connected) {
+    await showing;
+  } else {
+    showing.catch((error) => process.stderr.write(`${error.message}\n`));
+  }
+  return { url: server.url, shown: connected };
+}
+
+/// The open model's tree, as gcli tree gives it.
+export async function pageTree(path) {
+  await openInPage(path);
+  return (await viewerServer()).bridge.request("structure", {});
+}
+
+/// A picture of the open model, as PNG bytes.
+export async function pageRender(path, view) {
+  await openInPage(path);
+  const answer = await (await viewerServer()).bridge.request("render", view);
+  return Buffer.from(answer.png, "base64");
+}