ifc-lite AGENTS.md

Agent Guidelines: ifc-lite

Project-specific gotchas and guardrails: the things that bite you here and that you can't infer from the code. Generic good practice is assumed, not repeated. This file is the single source of truth; CLAUDE.md and .cursorrules just point here.

What this is

Browser-first IFC toolkit: a WebGPU web viewer plus a headless CLI/MCP/server. No first-party desktop app. Domain logic (decode, geometry, styling, export) lives in Rust crates under rust/* and is the source of truth for the server, CLI, SDK, and wasm; TypeScript packages under packages/* and apps under apps/* consume it (TS mostly does GPU upload and UI). Architecture docs: docs/architecture/overview.md.

Commands

• Install: corepack enable && pnpm install (Node 22.x, [email protected] pinned via packageManager).
• Build: pnpm build (turbo). WASM: pnpm build:wasm (needs Rust nightly + wasm-pack); pnpm build:wasm:fetch pulls the prebuilt wasm from npm when Rust is unavailable (e.g. Windows without WSL).
• Typecheck: pnpm typecheck (turbo, wasm-free: no Rust toolchain needed). This covers test sources too, which for a long time it did not: the root tsconfig.json excludes **/*.test.ts so tests never reach dist/, every packages/* config inherits that through tsconfig.packages.json, and exclude filters include — so a package's "include": ["src/**/*"] cannot pull its own tests back and 652 of 960 test files were in no typecheck program at all (#2457). Since vitest and tsx --test transpile per file without checking types, an unchecked test still runs while everything it asserts at type level (expectTypeOf, @ts-expect-error, a typed fixture) is silently unverified. Each package's typecheck script therefore runs scripts/typecheck-tests.mjs, which derives a no-emit test program from that package's own tsconfig and lists the test files under files — unlike include, files is not filtered by exclude. The generated <pkg>/tsconfig.tests.json is gitignored (rebuilt every run); the shared emit-off overrides live in tsconfig.tests.base.json. Do not "fix" a test-only type error by putting tests back into a package's emit tsconfig — that ships them to dist/.
• Test: pnpm test (turbo, TS); cargo test --workspace (Rust, not cargo check); pnpm test:wasm-contract (real wasm boundary); pnpm test:collab (collab pair).
• Always run typecheck/test through the root pnpm typecheck / pnpm test (turbo), never a package-local script (pnpm --filter <pkg> typecheck, cd packages/<pkg> && tsc --noEmit / vitest run) or an editor's TS server in isolation. turbo.json makes typecheck/test depend on ^build, but that dependency graph only fires through turbo; a package-local script or IDE process resolves workspace siblings straight off their dist/ (root tsconfig.json path-maps most packages to dist/*.d.ts; the rest, e.g. @ifc-lite/pointcloud, resolve via package.json#types → dist/index.d.ts). An unbuilt or stale sibling dist/ then throws "Cannot find module" / missing-export errors that name real files and symbols but describe no bug in the source — rebuild (pnpm build) before trusting a bypass-turbo result that disagrees with pnpm typecheck/pnpm test.
• Dev viewer: pnpm dev (full monorepo build, then --filter viewer dev; needs a built @ifc-lite/wasm).
• Fixtures: pnpm fixtures (tests skip when absent). Dead code: pnpm knip (TS) / cargo test --workspace (Rust).
• Publish: pnpm changeset; refresh the API-surface snapshot with pnpm api-surface:update.