Skip to content

AGENTS.md

Latest commit

 

History

History
75 lines (55 loc) · 4.11 KB

AGENTS.md

File metadata and controls

75 lines (55 loc) · 4.11 KB
Raw

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.