aspicio-dxf-viewer

<div align="center"> <img src="apps/demo/public/favicon.svg" width="72" height="72" alt="Aspicio logo" /> <h1>Aspicio</h1> <p><strong>DXF understanding for people, applications, and AI agents.</strong></p> <p><em>Aspicio</em> (Latin: "I look at")</p> <p> <a href="https://github.com/frontsail-ai/aspicio/actions/workflows/ci.yml"><img src="https://github.com/frontsail-ai/aspicio/actions/workflows/ci.yml/badge.svg" alt="CI" /></a> <a href="https://www.npmjs.com/package/@aspicio/core"><img src="https://img.shields.io/npm/v/%40aspicio%2Fcore?label=%40aspicio%2Fcore" alt="npm: @aspicio/core" /></a> <a href="https://www.npmjs.com/package/@aspicio/elements"><img src="https://img.shields.io/npm/v/%40aspicio%2Felements?label=%40aspicio%2Felements" alt="npm: @aspicio/elements" /></a> <a href="https://www.npmjs.com/package/@aspicio/react"><img src="https://img.shields.io/npm/v/%40aspicio%2Freact?label=%40aspicio%2Freact" alt="npm: @aspicio/react" /></a> <a href="https://www.npmjs.com/package/@aspicio/vue"><img src="https://img.shields.io/npm/v/%40aspicio%2Fvue?label=%40aspicio%2Fvue" alt="npm: @aspicio/vue" /></a> <a href="https://www.npmjs.com/package/@aspicio/svelte"><img src="https://img.shields.io/npm/v/%40aspicio%2Fsvelte?label=%40aspicio%2Fsvelte" alt="npm: @aspicio/svelte" /></a> <a href="https://www.npmjs.com/package/@aspicio/mcp"><img src="https://img.shields.io/npm/v/%40aspicio%2Fmcp?label=%40aspicio%2Fmcp" alt="npm: @aspicio/mcp" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a> </p> <p><a href="https://aspicio.frontsail.app"><strong>▶ Live demo</strong></a></p> </div>

Aspicio is an open-source (MIT), TypeScript-first DXF engine: one framework-free parse → tessellate pipeline that runs in the browser, in Node, and in Cloudflare Workers. A person gets an interactive WebGL viewer of a CAD drawing; an AI agent gets structured JSON facts and a rendered PNG of the same file. Every surface — the browser viewer, the web components and their React, Vue, and Svelte bindings, the headless renderer, the HTTP API, and the MCP server — is a thin adapter over the same engine, so a drawing is equally readable everywhere.

DXF bytes ──parse──▶ DxfDocument ──tessellate──▶ Tessellation ──┬─▶ WebGL renderer (viewer)
              (normalized model)      (batched geometry)        ├─▶ SVG string (export / API / MCP)
                                                                └─▶ DrawingSummary (describe)

How it's built: docs/architecture.md · behavior specs: docs/product-specs/

<img src="docs/sample-demo.png" alt="Aspicio viewing a sample floor-plan DXF — layer panel, colored geometry, text, and a dimension" />

Embed it

One embed, every flavor — and every path below renders the same web components, so the result is pixel-identical no matter which you pick.

Web components — plain HTML, any framework

One tag gives you the layer panel plus an interactive preview; no bindings needed:

<script type="module">
  import "@aspicio/elements";
</script>

<aspicio-embed src-url="/drawing.dxf" style="height: 480px"></aspicio-embed>

React

The same embed with idiomatic props and a ref exposing the full viewer, via @aspicio/react:

import { DxfEmbed } from "@aspicio/react";

<DxfEmbed src={file} style={{ height: 480 }} />;

Vue

Typed props and emits with unwrapped payloads, via @aspicio/vue:

<script setup>
import { DxfEmbed } from "@aspicio/vue";
</script>

<template>
  <DxfEmbed src-url="/drawing.dxf" style="height: 480px" />
</template>

Svelte

The same components as raw Svelte 5 source with typed callback props, via @aspicio/svelte:

<script>
  import { DxfEmbed } from "@aspicio/svelte";
</script>

<DxfEmbed srcUrl="/drawing.dxf" style="height: 480px" />

Vanilla TypeScript

Skip the ready-made UI and drive the viewer directly from @aspicio/core — bring your own chrome:

import { DxfViewer } from "@aspicio/core";

const viewer = new DxfViewer(document.querySelector("#preview")!);
await viewer.load(file); // File | Blob | ArrayBuffer | DXF text (ASCII or binary)

Headless — Node and Workers

Parse, describe, and render with no browser at all (server-side previews, thumbnails, pipelines):

import { parseDxfBytes, tessellate, describeDrawing, tessellationToSvg } from "@aspicio/core";

const doc = parseDxfBytes(bytes); // ASCII or binary DXF
const drawing = tessellate(doc);
const summary = describeDrawing(doc, drawing); // units, bounds, layers, texts…
const svg = tessellationToSvg(drawing);

What you get: WebGL rendering batched to one draw call per layer (large drawings stay interactive), broad entity coverage (lines, arcs, circles, ellipses, polylines with bulges, splines, TEXT/MTEXT, DIMENSION, SOLID/HATCH fills, nested INSERT blocks — anything unsupported is counted and reported, never fatal), a layer list with the colors that are actually drawn (per-entity overrides included, not just the layer table), measure with object snap, entity picking, paper-space layouts, SVG/PNG export, and first-class touch. Out of scope: editing and 3D.

Hand it to an agent

The same engine speaks MCP and HTTP, so an agent can read a drawing instead of guessing at it:

• describe_dxf — units, bounds, size, layers with effective colors, entity counts, and the drawing's text content. An agent reads a title block or a dimension value directly — no OCR, no vision round-trip.
• render_dxf — a PNG of the drawing the model can look at.
• view_dxf (hosted server) — an interactive in-chat viewer for the person in the conversation, via the open MCP Apps extension: pan, zoom, layer toggles, fullscreen, host light/dark theming. The widget is locked to the drawing the tool call delivered and makes no network requests; hosts without MCP Apps still get the structured facts.

<img src="docs/demo-widget.gif" alt="The in-chat viewer loading a 1.1 MB floor-plan DXF, toggling dimension and text layers, and expanding to fullscreen" />

Surface	Local files	URLs	Inline DXF
stdio MCP — npx -y @aspicio/mcp	✅	✅	✅
Hosted MCP — aspicio-api.frontsail.app/mcp	—	✅	✅
HTTP API — /describe, /render	POST body	✅	✅

Connect:

• Claude Code — one step installs the MCP server plus the bundled skills (aspicio-inspect-dxf, aspicio-embed): /plugin marketplace add frontsail-ai/aspicio then /plugin install aspicio@aspicio
• Codex — the same repo doubles as a Codex marketplace: codex plugin marketplace add https://github.com/frontsail-ai/aspicio, codex plugin add aspicio@aspicio, then codex mcp add aspicio -- npx -y @aspicio/mcp
• Any client that launches stdio MCP servers — register npx -y @aspicio/mcp
• Any client that supports remote MCP (Streamable HTTP) — point it at https://aspicio-api.frontsail.app/mcp (no install; speaks MCP, not a browser page)
• Plain HTTP — GET /describe?src=<dxf-url>, GET /render?src=<dxf-url>&format=png|svg; the API self-describes at /openapi.json

URL fetches are guarded (private-network blocking, size caps, redirect validation, timeouts). The stdio server reads local files in-process and never uploads the DXF to any Aspicio service — though, as with any tool result, your MCP client passes the returned summary or image to its model provider. Full details: privacy policy · terms.

Available today · direction

Everything above is shipped and live: viewer + demo, core, web components, React, Vue, and Svelte packages, headless describe/render, stdio and hosted MCP, the in-chat MCP Apps viewer, the HTTP API with OpenAPI, and plugin packaging for Claude Code and Codex.

Direction (intent, not commitments — see issues): MCP registry listings, structured entity queries and focused rendering, and an upload flow so remote surfaces can handle local files.

Packages

Package	Description
@aspicio/core	The viewer library: parsing, tessellation, rendering, camera, input
@aspicio/elements	Web components: <aspicio-embed>, <aspicio-preview>, <aspicio-layer-panel> — plain HTML, Svelte, any framework
@aspicio/react	React bindings: <DxfEmbed>, <DxfPreview>, <DxfLayerPanel>
@aspicio/vue	Vue 3 bindings: the same three components with typed props and emits
@aspicio/svelte	Svelte 5 bindings: the same three components as raw .svelte source
@aspicio/mcp	MCP server for AI agents: describe_dxf + render_dxf
@aspicio/api	DXF HTTP API server (private): /describe, /render, /mcp
@aspicio/widget	MCP Apps in-chat viewer widget (private), served by the api server
@aspicio/demo	Standalone demo app (private) — also the reference integration

How the viewer packages fit together: every framework path funnels into the same Lit web components — one implementation of the embed UI — which sit on the framework-free core. React, Vue, and Svelte get thin veneers with idiomatic props; plain HTML consumes the elements directly.

flowchart TD
    REACTAPP["React app"]
    HTMLAPP["Plain HTML / vanilla JS app"]
    VUEAPP["Vue app"]
    SVELTEAPP["Svelte app"]

    REACT["<b>@aspicio/react</b><br/>&lt;DxfEmbed&gt; · &lt;DxfPreview&gt; · &lt;DxfLayerPanel&gt;<br/><i>thin @lit/react veneer, API-stable</i>"]
    VUE["<b>@aspicio/vue</b><br/>&lt;DxfEmbed&gt; · &lt;DxfPreview&gt; · &lt;DxfLayerPanel&gt;<br/><i>thin Vue 3 veneer, typed emits</i>"]
    SVELTE["<b>@aspicio/svelte</b><br/>&lt;DxfEmbed&gt; · &lt;DxfPreview&gt; · &lt;DxfLayerPanel&gt;<br/><i>raw Svelte 5 source, compiled by your bundler</i>"]
    ELEMENTS["<b>@aspicio/elements</b><br/>&lt;aspicio-embed&gt; · &lt;aspicio-preview&gt; · &lt;aspicio-layer-panel&gt;<br/><i>Lit web components — the one embed-UI implementation</i>"]
    CORE["<b>@aspicio/core</b><br/>parse → tessellate → render<br/><i>camera · input · picking · SVG/PNG export · headless describe</i>"]

    REACTAPP -->|"idiomatic props, ref → DxfViewer"| REACT
    REACT -->|"wraps"| ELEMENTS
    HTMLAPP -->|"attributes + DOM events"| ELEMENTS
    VUEAPP -->|"idiomatic props + emits"| VUE
    VUE -->|"wraps"| ELEMENTS
    SVELTEAPP -->|"typed callback props"| SVELTE
    SVELTE -->|"wraps"| ELEMENTS
    ELEMENTS -->|"drives"| CORE
    HTMLAPP -.->|"or hand-rolled UI on the DxfViewer API"| CORE

    classDef pkg fill:#191c22,stroke:#4c8dff,color:#e7e3da
    classDef app fill:#1f232b,stroke:#3a3f4a,color:#9aa0ab
    class REACT,VUE,SVELTE,ELEMENTS,CORE pkg
    class REACTAPP,HTMLAPP,VUEAPP,SVELTEAPP app

Development

Toolchain: Vite+ (vp) on top of bun.

vp install       # install dependencies
vp run dev       # start the demo app
vp run ready     # check + test + build everything (the repo gate)

Testing, CI/deploy, releasing, and contribution guidance: CONTRIBUTING.md.

---

Aspicio is developed and maintained by FrontSail AI.