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

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, 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 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, while CAD reference parsing aligns with 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: Core scene builder that reads side-car data and assembles Three.js scenes from STEP file inputs.
• src/common/renderMeshScene.js: Handles the actual rendering of mesh scenes to either image files or WebGL canvases.
• 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: Manages viewer-specific rendering operations including part highlighting and exploded view generation.
• 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: Implements deterministic tessellation caching to ensure reproducible geometry generation.
• 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 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:

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:

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 for scene construction, 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, 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 and CAD reference parsing aligns with 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}