three-iges-loader

Agent instructions (AI & automation)

This file tells coding agents how to work on three-iges-loader safely and consistently.

Project goal

Parse IGES 5.3 CAD files into a typed model (iges-core) and tessellate wireframe geometry to Three.js (three-iges-loader). Surfaces and B-rep are out of scope unless the user explicitly requests a roadmap phase.

Monorepo layout

packages/iges-core/     ← Parser + geometry (NO three.js)
src/                    ← IGESLoader + toThreeGroup()
test/fixtures/          ← Shared IGES test files
docs/                   ← ARCHITECTURE.md, ROADMAP.md, ENTITY_IMPLEMENTATION.md

Rules

1. Never import three inside packages/iges-core.
2. One entity type per decoder file under entities/decoders/typeNNN.ts.
3. Register every decoder in entities/registry.ts.
4. Always add tests with a fixture in test/fixtures/ when adding behavior.
5. Do not implement Phase C/D surface/B-rep types unless asked — add a stub that returns unsupported and a roadmap note.
6. Transforms: only resolve/resolveReferences.ts composes type 124; decoders emit model-space coordinates.
7. Z-up → Y-up: only src/three/toThree.ts applies root rotation.
8. Prefer small PR-sized changes: one entity type or one parser fix per change.

Commands

pnpm install
pnpm --filter iges-core test    # core unit tests
pnpm test                       # core + integration
pnpm type-check
pnpm build

Releases & changesets

• User-visible changes to the published package require a changeset: run pnpm changeset and commit the file under .changeset/.
• Use patch (fix), minor (new entity/API), major (breaking).
• Do not bump package.json version manually — CI uses Changesets.
• See RELEASING.md and CONTRIBUTING.md.

Before finishing a task

• pnpm test passes
• pnpm type-check passes
• New entity documented in docs/ENTITY_IMPLEMENTATION.md
• Roadmap table updated in docs/ROADMAP.md if status changed
• pnpm changeset added if the change is user-visible (unless docs-only internal)

Common mistakes to avoid

• Splitting parameter data with naive split(';') on the whole P-section without Hollerith awareness — use paramTokenizer.ts.
• Mapping PD to entities only by array index — use DE parameterDataPointer when building parseParameterSection.
• Drawing NURBS by connecting control points — use sampleNurbsCurve.
• Applying rotation.x = -π/2 on every mesh — use root group in toThreeGroup only.

Entry documents

1. docs/ARCHITECTURE.md
2. docs/ENTITY_IMPLEMENTATION.md
3. docs/ROADMAP.md
4. CONTRIBUTING.md — human contributors
5. RELEASING.md — versioning & npm (maintainers)

Cursor Cloud specific instructions

Standard install/test/build/run commands live in the Commands section above; nothing here overrides them.

• Node version: This repo requires Node >=24 (engines), but the base VM’s default node on PATH (/exec-daemon/node) is v22. An nvm-managed Node 24 is installed and ~/.bashrc prepends it so interactive/login shells get Node 24 automatically. If you run a command and hit an engine/version error, you’re in a non-login shell using v22 — fix it in that shell with export PATH="$HOME/.nvm/versions/node/$(nvm version 24)/bin:$PATH" (or start bash -l). pnpm (10.33.4) is provided via corepack on the Node 24 install.
• Services: This is a library monorepo — no backend/DB/network services. End-to-end verification = pnpm test (Vitest: iges-core unit + loader integration). pnpm build uses tsup.
• Example viewer: pnpm dev:example runs a Vite + Three.js browser demo on http://localhost:3000 (dropdown switches IGES fixtures: point/line/slot/arc). It requires WebGL. In the headless VM, Chrome must be launched with --use-angle=swiftshader for software WebGL, otherwise the canvas is black with WebGLRenderer: A WebGL context could not be created in the console.

This site is open source. Improve this page.