feat(ifc): add optional IFC preview (BETA)

[p4535992]

Summary

• Draft / beta-quality implementation for discussion and architectural validation. This is not intended to be considered production-ready yet. It is an initial implementation of the IFC support proposed in issue [feature]: Add optional rendered IFC viewer support with an extensible That Open integration #267, submitted to confirm that the package boundary, That Open integration, public extension points, deployment model, and licensing direction are acceptable before further stabilization work.
• Adds opt-in .ifc / BIM preview support for @file-viewer/renderer-3d using a single pipeline for both small and large files: That Open Components IfcLoader -> web-ifc / WASM -> That Open Fragments + worker -> browser rendering.
• Keeps IFC-specific dependencies and runtime assets isolated behind @file-viewer/capability-ifc and @file-viewer/assets-ifc, rather than adding web-ifc, Components, Fragments, Worker, or WASM requirements to the default 3D / Engineering / All dependency closure.
• Adds an advanced extensibility bridge without attempting to mirror the complete That Open API: opaque Components / Fragments / importer configuration plus raw runtime access to components, world, fragments, loader, webIfc, importer, and model.
• Adds initial large-model safeguards, self-hosted Worker/WASM assets, open-license buildingSMART IFC fixtures, documentation, license notices, focused tests, and Chromium smoke coverage. CI is currently green, but broad real-world BIM compatibility and large-production-model profiling are still pending.

Related issue

#267

This is intentionally a Draft PR related to the implementation proposal in #267. I would prefer to confirm the architecture and dependency/license approach with maintainers before treating the issue as implemented or ready to close.

Change classification

• User-visible UI or rendering change
• Non-visual change
• File-format or renderer behavior
• Public API, package, Worker, WASM, or deployment-path change

Verification

Check	Result
pnpm install --frozen-lockfile	Pass (CI)
pnpm --filter @file-viewer/renderer-3d build && pnpm --filter @file-viewer/capability-ifc build	Pass (CI)
pnpm --filter @file-viewer/renderer-3d type-check && pnpm --filter @file-viewer/capability-ifc type-check	Pass (CI)
pnpm --filter @file-viewer/assets-ifc verify	Pass (CI)
pnpm audit:renderer-deps	Pass (CI)
pnpm exec vitest run test/ifc-optional-capability.spec.ts	Pass (CI)
Chromium IFC smoke test	Pass (CI)
pnpm verify:github-governance	Pass (CI)
pnpm build	Pass (CI)
pnpm type-check	Pass (CI)
pnpm test	Pass (CI)

The Chromium validation uses the committed IFC fixtures and exercises the actual That Open / Fragments runtime rather than a mocked renderer.

It covers regular IFC loading and a forced large-model classification while keeping the same rendering pipeline. It also verifies that the Fragments configuration pass-through reaches the runtime and that the underlying IfcLoader.webIfc instance is available through the advanced bridge.

These checks validate the current implementation mechanically, but they should not be interpreted as broad production validation of IFC compatibility or performance.

Sample / fixture evidence

• test/fixtures/ifc/Building-Architecture.ifc
• test/fixtures/ifc/Building-Structural.ifc
• The fixtures are sourced from the public buildingSMART Certification datasets. Source attribution, SHA-256 checksums, and CC BY 4.0 licensing information are committed alongside the fixture files.
• Upstream dataset: https://github.com/buildingSMART/Certification-datasets

Visual evidence

• Before: N/A: there is no currently enabled IFC preview implementation to provide a meaningful before screenshot.
• After: TODO before requesting non-draft review: attach a screenshot of one of the committed buildingSMART IFC fixtures rendered through the That Open / Fragments capability.

Risk and compatibility

• Affected packages/formats: .ifc; @file-viewer/renderer-3d; new optional @file-viewer/capability-ifc; new optional @file-viewer/assets-ifc; @thatopen/components; @thatopen/fragments; web-ifc; self-hosted Fragments Worker and web-ifc WASM assets.
• Compatibility or migration risk: this should currently be considered an experimental/beta implementation. The automated and Chromium tests are passing, but I have not yet validated it against a representative production corpus of IFC2x3 / IFC4 / IFC4.3 exports, very large BIM projects, low-memory devices, mobile browsers, or long-running model replacement sessions. I would prefer maintainer feedback on the architecture before investing further in that validation.
• Compatibility or migration risk: all IFC files now follow one implementation path: That Open Components -> IfcLoader -> web-ifc -> Fragments. There is no separate Flyfish direct web-ifc backend. This is intentional to avoid maintaining duplicate geometry, selection, property, camera, error-handling, and cleanup implementations.
• Compatibility or migration risk: IFC support is explicitly opt-in. Existing applications should not acquire web-ifc, That Open Components/Fragments, or their Worker/WASM runtime unless the IFC capability is installed and enabled. It is currently not automatically included in Engineering / All / Full presets.
• Compatibility or migration risk: largeModelThresholdBytes does not select a different renderer. Small and large IFC files use the same Fragments pipeline. The threshold is only used to avoid optional eager work for models classified as large. maxSourceBytes is an optional deployment policy that can reject a source before initializing the IFC runtime.
• Compatibility or migration risk: ifc.thatOpen.components, ifc.thatOpen.fragments, and ifc.thatOpen.importer intentionally act as opaque pass-through configuration. Flyfish does not maintain a second schema for those APIs. Advanced runtime objects are exposed as unknown, allowing consumers to use the types/API of the exact That Open version they install without making those third-party types part of Flyfish's stable API.
• Compatibility or migration risk: Worker and WASM assets are self-hosted. There is intentionally no public-CDN fallback, so deployments enabling IFC must publish the matching @file-viewer/assets-ifc files under the File Viewer runtime asset path.
• Compatibility or migration risk: web-ifc@0.0.77 is MPL-2.0. @thatopen/components@3.4.8 and @thatopen/fragments@3.4.7 are MIT. The optional IFC asset package keeps the applicable MPL-2.0 and MIT notices with redistributed runtime assets. I would specifically like maintainer confirmation that this dependency and licensing separation is acceptable before considering the implementation ready for merge.
• Rollback: remove or disable @file-viewer/capability-ifc and @file-viewer/assets-ifc. The normal renderer and existing presets remain independent of the optional IFC engine dependencies.

Checklist

• I added or updated focused automated coverage, or explained why it is not needed.
• I updated user-facing documentation or release notes when behavior or API changed, or marked them not applicable.
• I verified offline/private-deployment paths when changing Worker, WASM, fonts, vendor assets, or URLs.
• I did not commit secrets, customer files, private samples, generated caches, or unrelated changes.

[p4535992]

The implementation in #276 appears stronger than this draft in several areas, especially around Worker ownership, cancellation/disposal, installed-package validation, browser regression coverage, and general release readiness.

I think that structure is probably a better foundation for the final IFC implementation.

One capability from this draft that may still be worth preserving is the advanced That Open configuration bridge.

In #276, configure(context) provides useful post-load access to objects such as:

components
fragments
world
model
select

However, configuration of the IFC import pipeline itself is mostly internal to the renderer/Worker.

This draft explored an additional escape hatch for advanced consumers, conceptually:

createIfcRenderer({
  thatOpen: {
    components: {
      // pass-through configuration
    },

    fragments: {
      // Fragments runtime/settings pass-through
    },

    importer: {
      // importer processing options
    },
  },

  configure(context) {
    // post-load runtime customization
  },
})

The intent is not to expose every That Open option as a Flyfish-owned API.

Instead, it would allow advanced applications to use supported That Open importer / Fragments settings without requiring a new Flyfish release whenever the underlying libraries introduce additional options.

This seems particularly useful for future BIM-specific requirements while keeping the normal Flyfish IFC API small and stable.

So my preference would be to keep the more robust architecture from #276, while considering a small, explicitly advanced pass-through for importer / Fragments configuration.