Conway

Conway powers Bldrs Share, bringing high-quality, precision CAD to the web. This cutting-edge CAD engine, designed specifically for IFC and STEP formats, offers advanced geometric representation, enabling teams to open and visualize intricate models with exceptional accuracy and speed.

Conway includes two major subcomponents:

• IFC-gen, a mostly autogenerated TypeScript framework (~400kloc) for full API coverage parsing of the IFC 2x3, 4 compliant *.ifc files, and initial support for STEP AP2xx *.step files to support Automotive and 3D-printing applications. This is based on original work by hypar-io/IFC-gen, further developed by bldrs-ai for Conway. The runtime is fully open-source in this project. Please contact us for full access to our generation pipeline.
• conway-geom WASM core, bldrs-ai’s rewrite of web-ifc, engineered for high-performance and to support the full suite of open CAD standards within the IFC and STEP families.

Getting Started

Codex Setup

1. Ignore the below and refer to AGENTS.md.

Windows Setup

1. Install MinGW-64 and add g++.exe location to your PATH variable.

MacOS Setup

1. Install the gmake and node dependencies via Homebrew (brew install gmake node).

EMSDK Setup

1. Clone the EMSDK repo and add it to your path (see their instructions)
2. Conway is using 3.1.72

> cd $EMSDK
> ./emsdk install 3.1.72
> ./emsdk activate 3.1.72
> cd $CONWAY
conway> emcc -v
emcc (Emscripten gcc/clang-like replacement + linker emulating GNU ld) 3.1.72 (437140d149d9c977ffc8b09dbaf9b0f5a02db190)
...

Initial Build

Clone the Conway repository, then in the root directory of the repository:

# Make sure EMSDK environment is set up.
yarn setup
yarn build
yarn test

Example Uses

You can now load your IFC files. From the Conway root:

1. yarn browser model.ifc
2. yarn validator model.ifc "IFCWINDOW.OverallHeight <= 1500"

See the full example docs at Browser.md and Validator.md

Development

Update your client with changes since your last sync:

git pull
yarn setup

For the full build of both conway (TypeScript) and conway-geom (WASM subproject):

yarn build

Build just conway, not conway-geom, e.g. for updating just the Conway API or tools:

yarn build-incremental

For a full, clean rebuild:

yarn build-rebuild

You can also run the tests with jest:

yarn test

And finally, using the watch functionality, you can also have the code automatically rebuild on change and also re-run the tests using:

yarn build-test-watch

IFC Parser Console Test Application

Conway has a test application for parsing IFC step files to see the performance and included entity types at src/core/ifc/ifc_command_line_main.ts.

You can set up an alias to reference the latest package or build from source and use yarn cli:

alias conway='yarn cli'
OR
alias conway='npx --package=@bldrs-ai/conway@latest exec cli'

It can be run with:

conway [ifc file path]
# To output geometry
conway -g [ifc file path]
# Use -m 1024 for larger files

CLI Geometry Output Options

You can now output various geometry formats using the CLI:

conway [ifc file path] [options]

Examples:

• Output all geometry (default GLTF + GLB):

  conway index.ifc --geometry

• Output only GLTF:

  conway index.ifc --geometry --gltf

• Output only GLB:

  conway index.ifc --geometry --glb

• Output GLTF with Draco compression:

  conway index.ifc --geometry --gltf-draco

• Output GLB with Draco compression:

  conway index.ifc --geometry --glb-draco

• Run geometry processing without saving output files:

  conway index.ifc --geometry --nooutput

You can also combine flags as needed. For example:

conway index.ifc --geometry --gltf-draco --glb-draco

Run conway --help for the full list of available flags and options.

The included index.ifc in the repo is recommended for testing.

Profiling WASM Builds in Node

Profiling Conway, including building a Conway-Geom WASM binary with DWARF information and generating a flame graph with WASM symbols, is possible via the following steps:

1. Run build-profile-conway_geom from Conway's package.json
2. Profile your app:

node --prof --experimental-specifier-resolution=node ./compiled/src/ifc/ifc_command_line_main.js <model.ifc> -g

3. An isolate*.log file will be generated. Run:

node --prof-process --preprocess -j isolate*.log > v8.json # generate a V8 log

4. Go to https://mapbox.github.io/flamebearer/ and drop the log file to see a detailed flame graph.

Problems with renaming in GIT merges

Because of the large number of files in conway that are code changes sometimes causing large modifications in merges, especially if generation locations are changed, it's sometimes necessary to up the limit of the number of renames in the git config for merging. It can be done like so:

git config merge.renameLimit 99999

You may also wish to use a low rename threshold no-commit merge strategy for some of these situations to increase likelyhood that files will be related in the merge process and to track some of the more complicated changes:

git merge -X rename-threshold=25 --no-commit

CI and Testing

Every PR is gated on two checks defined in .github/workflows/build.yml:

| Job | What it does | |---|---| | build | yarn install, WASM + TS compile (WASM cached on the conway-geom submodule SHA), yarn test, yarn lint. | | run-ifc-regression | needs: build. Reuses the same WASM cache. Runs the regression batch against the pinned test-models tag, posts a per-PR comment with failed.csv / errors.csv / perf summaries, and uploads the candidate npm tarball + perf.csv as workflow artifacts. |

A merge to main re-runs those two jobs and then chains into auto-publish (see Releases below).

Regression batch

The same batch the regression CI job runs can be invoked locally — see regression/README.md for digest / verbose / batch modes and the catalog of model fixtures. The CI pinned tag is TEST_MODELS_TAG near the top of build.yml.

Performance benchmarks

Tier 1 — Conway-only perf in CI (live). Every regression run emits a perf.csv of parseTimeMs / geometryTimeMs / totalTimeMs / rssMb / heapUsedMb / heapTotalMb per model. The top-10 slowest are posted in the PR comment; the full CSV is uploaded as a workflow artifact. This piggybacks on the existing regression batch so cost is ~0 extra runner minutes.

Tier 2 — full headless-three perf (planned, #314). A perf-three job on push: main that runs scripts/benchmark.cjs against a clone of headless-three, installing the candidate Conway tarball as H3's @bldrs-ai/conway dep. Captures PNG renders + per-model timings via H3's rendering server, including a parallel job for test-models-private. Tracked in #314.

Releases

Releases are continuous. Every green merge to main auto-tags and publishes to npm at the default latest dist-tag. The version is <major>.<PR>.<commit> where:

• major comes from package.json on main (only the first segment; the other two are recomputed on every release)
• PR is the GitHub PR number that produced the merge commit
• commit is git rev-list HEAD --count at the merge commit (the global commit position)

So a merge of PR #321 at the 985th commit on main publishes as 1.321.985. Each release is uniquely traceable to a PR and a commit.

The auto-publish job lives in .github/workflows/build.yml and runs as needs: [build, run-ifc-regression] on push: branches: [main]. It parses the PR number from the merge commit message, stamps the computed version into package.json + src/version/version.ts in CI's working tree (not committed back), rebuilds, publishes to npm, and then tags the merge commit.

Auth: npm Trusted Publishing via GitHub OIDC. A Trusted Publisher configured at npmjs.com on @bldrs-ai/conway is bound to this repo + build.yml. No long-lived NPM_TOKEN secret is used; the workflow gets a short-lived publish token per run via OIDC.

Normal flow: ship a change

1. Open a PR with your change. CI runs build and run-ifc-regression.
2. Merge once both checks are green.
3. On main push, CI re-runs build + run-ifc-regression, then auto-publish tags and ships. Watch the workflow run in the Actions tab; the new version is on npm within ~5-10 min of the merge.

Bumping major

Edit the version field in package.json on a PR — only the first segment matters (the PR and commit parts are recomputed). For example, change "version": "1.0.0" to "version": "2.0.0" to start the 2.x.x line. The first auto-publish after that lands ships 2.<PR>.<commit>.

There is no minor bump — PR lives in that slot — so increasing sequential versions across the 1.x line look like 1.300.x, 1.301.x, etc., as PRs land.

Rolling into headless-three and Share

The same flow applies to both — do H3 first, then Share:

cd $H3_DIR
git fetch upstream                                       # or origin if not on a fork
git checkout -b conway-<VERSION> upstream/main
# Edit package.json dep for @bldrs-ai/conway to "<VERSION>"
yarn install
yarn build && yarn test
yarn serve
# Smoke test the local candidate: load all sample models, load a local model,
# exercise dialogs, etc.
git add . && git commit -m "Upgrade conway from <OLD> to <VERSION>"
git push origin HEAD

Then:

1. Send PR for review.
2. On merge, Netlify auto-builds and deploys to prod; watch the deploy logs.
3. Smoke test prod (same checks as local).
4. Post in #bot or #share: "New Conway in prod" with a link to the changelog.

Blessing a stable version

After Share prod is verified on a given Conway version:

# Create the GitHub release from the auto-pushed tag
gh release create <VERSION> --generate-notes

# Promote the npm package to the stable dist-tag
npm dist-tag add @bldrs-ai/conway@<VERSION> stable

Roadmap

The CI / release pipeline is now continuous, but there are tracked follow-ups to deepen its coverage. Big items first.

#314 — Performance benchmarks in CI

Tier 1 — Conway-only perf (done): the regression batch now emits a per-model perf.csv (parse/geometry/total time + RSS/heap MB), piggybacking on the existing run so there's no extra runner cost. Top-10 slowest models appear in each PR comment; the full CSV uploads as an artifact. See "Performance benchmarks" above.

Tier 2 — full headless-three perf (next): an end-to-end render-and-time job that runs scripts/benchmark.cjs against a clone of headless-three. To avoid the local yarn link toolchain, the job installs the candidate Conway tarball (produced by run-ifc-regression) as H3's @bldrs-ai/conway dep and pins H3_TAG in build.yml. Gated to push: main to keep PR runtime down while still exercising every release. A sibling job runs against test-models-private using secrets.TEST_MODELS_PRIVATE_TOKEN, never on PR events (so forks can't leak the secret), and uploads results as org-scoped artifacts. Delta vs. the previous release lands in the auto-publish summary.

#315 — Bump pinned TEST_MODELS_TAG

The regression batch in build.yml is pinned to [email protected]. If newer stable tags exist, bumping picks up coverage of more recent fixtures. The bump itself is a one-line change; the work is triaging whatever new diffs appear on a no-op PR run.

#316 — CI waterfall

Mostly done: build → run-ifc-regression is in place and shares the WASM cache. The only remaining piece is #314 above (the third leg of the waterfall).