# What Is the cadgen-js Package? Purpose and Architecture in text-to-cad

> Discover the cadgen-js package, the framework-agnostic JavaScript runtime for CAD rendering and motion within the text-to-cad ecosystem. Explore its purpose and architecture.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: deep-dive
- Published: 2026-09-11

---

**The cadgen-js package provides the shared, framework-agnostic JavaScript runtime that powers all CAD-related rendering and motion in the text-to-cad ecosystem.**

The cadgen-js package serves as the central JavaScript runtime within the earthtojake/text-to-cad repository, handling the transformation of cached geometry files into pixels, meshes, and animated motion. This framework-agnostic library contains the common core used by every consumer in the ecosystem, from the CAD Viewer to the documentation site, ensuring consistent rendering across all JavaScript environments.

## Core Purpose of the cadgen-js Package

### Framework-Agnostic Runtime Architecture

According to the repository's [`README.md`](https://github.com/earthtojake/text-to-cad/blob/main/README.md), cadgen-js operates as a **runtime-only** package designed to function independently of frontend frameworks. Unlike typical CAD visualization tools that couple rendering logic with React components, this package depends solely on low-level graphics libraries `three` and `meshoptimizer`, as specified in [`packages/cadgen-js/package.json`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen-js/package.json) lines 21-24. The absence of React, Python, or other framework-specific code ensures that the package can execute in both browser and Node.js environments without modification.

### Synchronization with Python Backend

The architecture follows strict "laws" that maintain lockstep compatibility with the Python counterpart. Specifically, the kinematics runtime in cadgen-js directly corresponds to [`cadgen/_internal/kinematics_fk.py`](https://github.com/earthtojake/text-to-cad/blob/main/cadgen/_internal/kinematics_fk.py), while CAD reference parsing aligns with [`cadgen/cad_ref_syntax.py`](https://github.com/earthtojake/text-to-cad/blob/main/cadgen/cad_ref_syntax.py). These contracts are enforced through synchronization tests throughout the repository, ensuring that JavaScript-based rendering produces identical results to the Python-based generation logic.

## Key Components and File Structure

### Scene Building and Headless Rendering

The package exposes several critical entry points for constructing and rendering CAD scenes:

- **[`src/common/cadScene.js`](https://github.com/earthtojake/text-to-cad/blob/main/src/common/cadScene.js)**: Core scene builder that reads side-car data and assembles Three.js scenes from STEP file inputs.
- **[`src/common/renderMeshScene.js`](https://github.com/earthtojake/text-to-cad/blob/main/src/common/renderMeshScene.js)**: Handles the actual rendering of mesh scenes to either image files or WebGL canvases.
- **[`src/common/headlessRenderEntry.js`](https://github.com/earthtojake/text-to-cad/blob/main/src/common/headlessRenderEntry.js)**: Entry point utilized by the snapshot builder for server-side rendering without a browser context.

### Viewer-Specific Utilities

For interactive applications, the package provides specialized modules:

- **[`src/lib/viewer/partRendering.js`](https://github.com/earthtojake/text-to-cad/blob/main/src/lib/viewer/partRendering.js)**: Manages viewer-specific rendering operations including part highlighting and exploded view generation.
- **[`src/lib/viewer/partVisualState.js`](https://github.com/earthtojake/text-to-cad/blob/main/src/lib/viewer/partVisualState.js)**: Controls visual state transitions for individual parts within the assembly.

### Deterministic Export and Caching

The runtime guarantees byte-for-byte output consistency through specialized modules:

- **[`src/lib/surf/tessellationCache.js`](https://github.com/earthtojake/text-to-cad/blob/main/src/lib/surf/tessellationCache.js)**: Implements deterministic tessellation caching to ensure reproducible geometry generation.
- **[`src/lib/glb/writeGlb.js`](https://github.com/earthtojake/text-to-cad/blob/main/src/lib/glb/writeGlb.js)**: Writes GLB files from rendered meshes, used by Node-based builders in the bundling pipeline.

## Dependency Graph and Consumers

### Graphics Dependencies

The package maintains a minimal dependency footprint, pinning specific versions of:

1. **three**: The underlying 3D graphics library
2. **meshoptimizer**: Geometry optimization utilities

These dependencies are declared in [`packages/cadgen-js/package.json`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen-js/package.json) and support both browser snapshots and Node-based build processes.

### Downstream Consumers

The "DEPENDED ON BY" section in the README identifies three primary consumers:

- **`apps/viewer`**: The CAD Viewer client imports cadgen-js to render STEP/GLB files, handle exploded views, execute part highlighting, and process measurements.
- **`apps/docs`**: The documentation site uses the same runtime to generate interactive CAD previews for documentation examples.
- **`scripts/bundle/`**: Custom bundlers package the source into final `_runtime/` bundles for distribution to both browser and Node environments.

## Practical Implementation Examples

### Headless Rendering in Node.js

To render CAD geometry without a browser environment, import the headless utilities and scene builders:

```javascript
import { cadScene } from 'cadgen-js/common/cadScene.js';
import { renderMeshScene } from 'cadgen-js/common/renderMeshScene.js';
import { headlessRenderEntry } from 'cadgen-js/common/headlessRenderEntry.js';

// Load a STEP file (cached geometry) – the path is supplied by the viewer side-car.
const scene = await cadScene.loadFromStep('myPart.step.json');

// Render a still image (png) using the headless entry point.
await headlessRenderEntry({
  scene,
  output: 'output.png',
  width: 800,
  height: 600,
});

```

### Interactive Part Highlighting

For viewer applications requiring user interaction, utilize the part visualization utilities:

```javascript
import { partRendering } from 'cadgen-js/lib/viewer/partRendering.js';
import { partVisualState } from 'cadgen-js/lib/viewer/partVisualState.js';

const partId = 'part-23';
const highlighted = partVisualState.highlight(partId);
partRendering.render(highlighted);

```

## Summary

- The cadgen-js package provides the framework-agnostic JavaScript runtime for all CAD rendering in the text-to-cad ecosystem.
- It contains zero framework-specific code, depending only on `three` and `meshoptimizer` for graphics operations.
- The package synchronizes with Python backend components through strict architectural contracts enforced by tests.
- Key modules include [`cadScene.js`](https://github.com/earthtojake/text-to-cad/blob/main/cadScene.js) for scene construction, [`headlessRenderEntry.js`](https://github.com/earthtojake/text-to-cad/blob/main/headlessRenderEntry.js) for server-side rendering, and viewer utilities for interactive manipulation.
- Primary consumers include the CAD Viewer application, documentation site, and bundling scripts that create distribution packages.

## Frequently Asked Questions

### What is the primary purpose of the cadgen-js package?

The cadgen-js package serves as the shared JavaScript runtime that converts cached geometry files into renderable pixels, meshes, and animations across all applications in the earthtojake/text-to-cad repository. It functions as the single source of truth for CAD rendering logic, ensuring consistent visualization between the CAD Viewer, documentation site, and headless build processes.

### How does cadgen-js differ from the CAD Viewer application?

While the CAD Viewer (`apps/viewer`) is a specific client application with user interface components, cadgen-js is the underlying runtime library that the Viewer imports to perform actual rendering operations. The package contains no React or UI code; it provides only the computational and graphical utilities needed to display CAD geometry, making it reusable by multiple frontend implementations.

### What dependencies does the cadgen-js package require?

The package requires only two pinned dependencies: `three` (the 3D graphics library) and `meshoptimizer` (for geometry optimization). As documented in [`packages/cadgen-js/package.json`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen-js/package.json), the runtime intentionally excludes React, Python bindings, or other framework-specific libraries to maintain maximum portability across execution environments.

### How does cadgen-js maintain compatibility with the Python backend?

The repository enforces strict "laws" that bind the JavaScript runtime to Python implementations, particularly ensuring that kinematics calculations in cadgen-js match those in [`cadgen/_internal/kinematics_fk.py`](https://github.com/earthtojake/text-to-cad/blob/main/cadgen/_internal/kinematics_fk.py) and CAD reference parsing aligns with [`cadgen/cad_ref_syntax.py`](https://github.com/earthtojake/text-to-cad/blob/main/cadgen/cad_ref_syntax.py). Automated synchronization tests verify that both runtimes produce identical geometric and kinematic results, preventing drift between the generation and rendering pipelines.