pcbjam/docs/features/occ-split/README.md

OCC split — move OpenCASCADE out of pcbnew.wasm into a lazy worker service

Feature doc for branch occ-lazy-load (worktree ../kicad-wasm-occ-lazy-load), 2026-07-02. Hard constraints: native wasm-EH, pthreads, Asyncify, NO JSPI, NO dynamic linking (dlopen/SIDE_MODULE/wasm-split are RED — §2). Codebase claims carry file:line (kicad @ 9d77139, root @ 9787efc).

---

TL;DR

OpenCASCADE (OCC) is ~30% of pcbnew.wasm (~19.5 MiB base code → ~35–40 MB after Asyncify) and serves two features: parsing STEP/IGES component models for the 3D viewer (working — and the primary model path, §1a), and STEP/3D export (broken — its UI spawns a kicad-cli subprocess, impossible in a browser, §1b).

The plan: move OCC and both features into a standalone occ_service module — own emscripten instance and memory, running in a Web Worker, fetched on demand — leaving pcbnew.wasm OCC-free.

• pcbnew.wasm: ~146 → ~109 MB raw (the 2D-editing download, ~25–30% less transfer).
• occ_service.wasm: ~25–45 MB raw estimate (our OCC compiles -O1; the worker also carries the board parser — measure), fetched only when a STEP model must be parsed or the user exports.
• 3D viewer behavior is unchanged (same parser code, executed in the worker; §3); export starts working for the first time.

The pcbnew↔service API is two functions:

pcbnew.wasm (no OCC)                          occ_service.wasm (worker, lazy)
Export dialog OK ─► occExport(boardSexpr, paramsJson) ──► parse + EXPORTER_STEP ─► bytes ─► downloadBytes()
oce3d_Load shadow ─► occLoadModel(fileBytes, ext) ──────► OCC parse + tessellate ─► scenegraph-cache bytes ─► S3D::ReadCache

---

1. The two OCC consumers today

OCC is reached by exactly two subsystems (grep-proven across kicad/ for TopoDS/BRep/Standard_/STEPControl/…). Everything else — 2D editor, GAL, DRC, router, kimath, the 3D scene build and raytracer (board geometry is native earcut tessellation), eeschema, gerbview — is OCC-clean.

1a. Component-model import — WORKING, and OCC is its primary parser

The 3D viewer's format loaders are static libraries in the wasm build (upstream loads them as dlopen plugins; wasm has no dlopen, so they're linked in with per-TU symbol renames and a registry):

• plugins/3d/vrml (vrml3d_*) — VRML/WRL/X3D, no OCC.
• plugins/3d/oce (oce3d_*) — STEP/IGES via OCC (loadmodel.cpp: STEP/IGES readers → BRepMesh_IncrementalMesh → SCENEGRAPH triangles).
• Registry: 3d-viewer/3d_cache/pcbjam_static_3d_plugins.cpp (EMSCRIPTEN-only TU) feeds both into the plugin manager; 3d-viewer/CMakeLists.txt links s3d_plugin_vrml s3d_plugin_oce for EMSCRIPTEN.

Model files arrive lazily: when the filename resolver can't find a model, S3D_CACHE::load (3d_cache.cpp:156-161) calls PCBJAM_3D::EnsureModelFile (3d-viewer/3d_cache/pcbjam_model_fetch.cpp) — an EM_ASYNC_JS asyncify suspend that asks the JS provider (kicadLibs.request, kind model3d; web/standalone/src/wasm/libs/models-{source,bridge}.ts), which fetches R2 CDN → IndexedDB cache → MEMFS and returns the absolute path. Once per unique model, memoized, e2e-covered (tests/kicad/3d-viewer-models.spec.ts).

Key consequence for this feature: the published model library (kicad-packages3D 10.x) is STEP-only — .wrl asks are served .step bodies by the bridge's fallback map (models-bridge.ts:106-117), and the served extension picks the plugin. So for library models, oce/OCC is the parser that runs; VRML handles only project-local legacy files. Any OCC removal must therefore carry this path along, gated by the 3d-viewer-models spec + screenshots staying green.

1b. STEP/3D export — BROKEN (its UI spawns a subprocess)

DIALOG_EXPORT_STEP (File → Export → STEP/GLB…) does not run the exporter in-process, even on desktop. On Export (pcbnew/dialogs/dialog_export_step.cpp:548-708) it locates the kicad-cli binary, builds a command string from the dialog controls (… pcb export step --no-dnp --subst-models --output …), and spawns it via wxExecute; the child process maps the flags to JOB_EXPORT_PCB_3D and runs PCBNEW_JOBS_HANDLER::JobExportStep (pcbnew_jobs_handler.cpp:532, EXPORTER_STEP ctor at :648) — OCC executes in the child. In the browser this fails twice: we ship no kicad-cli, and wasm has no processes (wxExecute needs fork/exec). The exporter cluster (exporters/step/* + exporters/u3d/*, whose only external caller is that jobs handler) is linked but unreachable from any UI path.

Scale note: in time, both consumers are batch — once per unique model at scene build, once per export click. Inside, they make thousands of fine-grained OCC calls (step_pcb_model.cpp, loadmodel.cpp) — which is why the split boundary is files/bytes handed to two entry points, never OCC's own API.

---

2. Architecture: two RPC functions, separate instance, Web Worker

Every form of Emscripten dynamic linking is RED here (each constraint breaks it independently): dlopen can't rewind through asyncify (emscripten #13049), pthread workers re-compile side modules (#17078), EH-across-boundary is fragile (#22285), wasm-split needs PROXY_TO_PTHREAD (GUI is on our main thread). Full analysis: docs/features/perf/bundle-size.md §4 (bundle-size branch).

A separate emscripten instance in a dedicated Worker sidesteps all of it — own Module, own memory, own runtime; data crosses by copying. For export this mirrors what desktop already does (kicad-cli child process ↔ worker; flags ↔ params JSON; file on disk ↔ bytes back). For import it relocates where the parse executes; the delivery pipeline (CDN→IDB→MEMFS) and everything downstream of SCENEGRAPH are untouched.

• Transport = postMessage + transferable ArrayBuffers (move semantics, zero-copy). The only real copies are into/out of each wasm heap — fundamental (a module addresses only its own linear memory), ms-scale on MB payloads vs seconds-scale OCC work. SharedArrayBuffer views were considered and rejected: both heaps are already SABs (-pthread), but direct sharing grants the worker write access to the editor heap and couples us to cross-heap pointer lifetime + shared-memory-growth semantics across 3 engines, for no measurable win. Cancel = worker.terminate() + re-boot.
• Export result bytes never enter pcbnew's heap: worker → provider → Blob → downloadBytes() (web/standalone/src/lib/download.ts:6); C++ receives a small status/report JSON. Import results (scenegraph-cache bytes) do enter — S3D::ReadCache consumes them there.
• Neither OCC job suspends internally (no emscripten_sleep/modal/PROGRESS_REPORTER in either path), so the service builds -sASYNCIFY=0 — no ~2× asyncify tax. External precedent: andymai/occt-wasm (OCCT in a Worker, -fwasm-exceptions, no asyncify → 20.8 MB / ~4 MB brotli); kovacsv/occt-import-js (STEP→mesh).

Latency reality: the 2D editor (the common session) never fetches the service. A 3D view of a board with library models effectively always will (the 10.x library is STEP-only) — one fetch (~5–9 MB brotli), then IDB-cached like the models themselves.

---

3. Design decisions

• Callee-shadowing, not caller-#ifdefs. Both features reduce to one shadowable function each, and the wasm build swaps in replacement definitions (the established PCBNEW_WASM_STUBS pattern):
  • EXPORTER_STEP ctor/dtor/Export() — shadow TU in our repo (wasm/stubs/); pcbnew_jobs_handler.cpp and every other caller compile untouched and keep working.
  • oce3d_Load (+ the oce3d_* metadata getters the registry needs — mirroring oce.cpp's extension/filter answers) — shadow TU replaces linking s3d_plugin_oce; the registry, plugin manager, S3D_CACHE, and scene build compile untouched.
• UI stays exactly as desktop. Dialog, menu, actions untouched. The single KiCad source #ifdef in the whole feature is in dialog_export_step.cpp at the wxExecute spawn site: read the same controls, fill EXPORTER_STEP_PARAMS, call EXPORTER_STEP(…).Export() directly — the shadow does the rest. (There is no function to shadow there; the divergence is the process spawn.)
• 3D viewer parity is a hard gate. Same parser code (loadmodel.cpp) compiled into the service; results return via KiCad's own scenegraph serialization (S3D::WriteCache/ReadCache, plugins/3dapi/ifsg_api.h — the on-disk model-cache format). 3d-viewer-models.spec.ts + the screenshot gate must stay green.
• Params JSON = the official job JSON. JOB_EXPORT_PCB_3D registers every field as a serializable JOB_PARAM (common/jobs/job_export_pcb_3d.cpp:94-149); the bridge uses KiCad's own (de)serialization, no invented schema. Every dialog option is honored (formats STEP/GLB/XAO/BREP/PLY/STL + all flags).
• Export component models = desktop parity in v1. Models embedded in the board file travel inside the sexpr and work; disk-path references the worker can't see hit EXPORTER_STEP's missing-file warn+skip, like desktop with a broken path. The CDN model pipeline (§1a) is the natural upgrade to full component embedding — follow-on (§7).
• Alternative rejected — wasm kicad-cli in a worker: same architecture, but stock kicad-cli links both kifaces + all job handlers (~100+ MB lazy module); trimming it is more fork surgery than the one dialog #ifdef; emulating the spawn (argv string parsing, wxProcess event plumbing) outweighs it; and the real glue (board in, bytes out) is needed either way.

---

4. Implementation

Stage 1 — occ_service target (build + entry, no pcbnew changes)

Template = sym_convert, the proven gated headless -sASYNCIFY=0 KiCad module (kicad/eeschema/CMakeLists.txt:796-830), adapted from run-once Node CLI to persistent worker embind:

• Target lives in the superproject: wasm/occ-service/CMakeLists.txt, hooked from the kicad fork's top-level CMakeLists via add_subdirectory( ${KICAD_WASM_LAYER}/occ-service ) under option( KICAD_OCC_SERVICE_WASM … OFF ) (the wasm/editor pattern; kicad keeps only the option + hook + the exporter-source CACHE INTERNAL export). Linked like sym_convert: full pcbnew kiface libraries + s3d_plugin_oce + kicad_3dsg + ${OCC_LIBRARIES} + LINKER:--allow-multiple-definition, in its own configured tree.
• Size mechanism = link-time -Oz whole-module DCE (as sym_convert documents, eeschema/CMakeLists.txt:825-827): the only roots are the embind entry + runtime, so editor/GAL/tool code pulled via the kiface objects is stripped. Fallback if fat: add_library( … STATIC $<TARGET_OBJECTS:pcbnew_kiface_objects> ) for object-granularity pruning. Measure first.
• LINK_FLAGS = -Oz -g0 -sASYNCIFY=0 --pre-js …/occ_service_pre.js -sMODULARIZE=1 -sEXPORT_NAME=OccService --bind -sENVIRONMENT=worker,node -sEXIT_RUNTIME=0, keep -pthread + the EH triple (env.sh:46) + the inherited 2N+8 pre-warmed pthread pool — load-bearing; see the threading note in §7 for the confirmed Chromium deadlock it prevents. NOT -sINVOKE_RUN/-sEXIT_RUNTIME=1/-sNODERAWFS (sym_convert's CLI model).
• Entry wasm/occ-service/occ_service_main.cpp, embind (compiled inside the CMake target so its defines match the linked objects — the embind vtable-skew class):
  • occExport(boardSexpr, paramsJson) → bytes: headless board load replicating pcbnew_scripting_helpers.cpp:96-235 (standalone SETTINGS_MANAGER, default project, PCB_IO_MGR::Load(KICAD_SEXP), SetProject) — that file itself is KICAD_SCRIPTING-gated, so the ~30-line pattern is replicated, not linked; paramsJson → JOB_EXPORT_PCB_3D::FromJson → the JOB→EXPORTER_STEP_PARAMS mapping of pcbnew_jobs_handler.cpp:630-648 → EXPORTER_STEP(…).Export() to MEMFS → bytes.
  • occLoadModel(fileBytes, ext) → bytes: write to MEMFS with the right extension (extension picks STEP vs IGES inside), call the real oce3d_Load, S3D::WriteCache the returned SCENEGRAPH → return the cache bytes.
  • wasm/occ-service/occ_service_pre.js: in-memory wxConfig store (copy sym_convert_pre.js).
• Build wiring, mirroring sym_convert: scripts/kicad/build-occ_service.sh; the case/option/tool-gates in scripts/kicad/build-kicad-target.sh; docker/build.sh VALID_APPS/validation/subdir + skip host post-processing and the asyncify pass for this target.
• Verify: Node (-sENVIRONMENT=worker,node) unit run — occExport on a real .kicad_pcb (validate the STEP round-trips, e.g. occt-import-js), occLoadModel on a real .step (cache bytes non-empty, ReadCache-able).

Stage 2 — bridges + JS provider (pcbnew gains the worker paths; OCC still linked)

• Export shadow wasm/stubs/exporter_step_stub.cpp (appended to PCBNEW_WASM_STUBS): Export() serializes the live BOARD to sexpr (in-memory PCB_IO_KICAD_SEXPR), builds the job JSON, calls js_occRequest (EM_ASYNC_JS, near-copy of the main-thread path of pcb_io/pcbjam_fp/pcb_io_pcbjam_fp.cpp:58-95; the js_* name is auto-covered by scripts/common/asyncify-imports.txt), returns the status/report JSON to the caller; bytes go provider → Blob → downloadBytes().
• Import shadow wasm/stubs/oce_plugin_stub.cpp: the full oce3d_* flat-C surface with oce.cpp's metadata answers; oce3d_Load(path) reads the file from MEMFS (already materialized by EnsureModelFile), ships bytes + ext via the same js_occRequest channel, writes the returned cache bytes to a temp MEMFS path, S3D::ReadCache → SCENEGRAPH*. Suspending here is proven legal — EnsureModelFile already asyncify-suspends inside the same S3D_CACHE::load call path.
• Dialog seam: the one #ifdef __EMSCRIPTEN__ at dialog_export_step.cpp:568/:708 (controls → params → EXPORTER_STEP(…).Export()).
• JS provider/worker: installOccService() sets globalThis.occService = { request } (copy installLibsProvider, web/standalone/src/wasm/libs/source.ts:245-386). First request lazily fetches + boots the module in a dedicated Worker (manifest-resolved, MODULARIZE factory; boot pattern site/public/gerber-demo/boot.js; reuse the cross-origin blob-importScripts shim web/standalone/src/wasm/boot.ts:113-137 for the worker + its nested pthread workers); transferables both ways; export results → downloadBytes(), import results → back to the caller. Manifest entry in web/standalone/src/wasm/wasm-assets.ts. Inside the blob wrapper every asset path must be absolutized against the glue's URL — locateFile: (f) => new URL(f, GLUE).href — because a blob: worker has no http base: a string-concat base works for absolute CDN URLs but a root-relative base like /wasm/ fails URL parsing in the worker, aborting the module before the .wasm request even hits the network. Export download names guard against the dialog's empty-stem default (.step → export.step). The worker-side wrapper is ONE shared plain-JS file, web/standalone/src/wasm/occ-worker.js (app imports it via vite ?raw; the e2e harness stub reads it off disk) — the host prepends a one-line self.OCC_GLUE_URL = … prelude to the blob. In tests the provider is installed ambiently by tests/kicad/fixtures.ts as an init script.
• In this stage the shadows can ship dark (service used only under a flag or test) — pcbnew still links OCC, so behavior is unchanged until Stage 3 flips.

Stage 3 — unlink OCC from pcbnew (the payoff, gated by green e2e)

All in kicad/pcbnew/CMakeLists.txt + kicad/3d-viewer/CMakeLists.txt, house importer-gate style:

1. Exporter sources (exporters/step/* + exporters/u3d/*) → PCBNEW_OCC_EXPORTERS, appended to PCBNEW_EXPORTERS only if( NOT EMSCRIPTEN ) (the service target compiles the variable).
2. ${OCC_LIBRARIES} on pcbnew_kiface_objects under if( NOT EMSCRIPTEN ). find_package(OCC) + top-level OCC include dirs stay (headers still compile).
3. 3d-viewer: for EMSCRIPTEN link s3d_plugin_vrml + the import shadow instead of s3d_plugin_oce.
4. Export + import shadows go live (they are the only definitions now).

Gate: full kicad e2e in all 3 engines + 3d-viewer-models.spec.ts + screenshot diff — STEP component models must render identically through the worker. Then measure.

---

5. Verification & benchmarks

• Stage-by-stage: Node unit (Stage 1); e2e with the service behind a flag (Stage 2); the full gate on Stage 3 (above).
• New e2e specs (all 3 engines, wired like 3d-viewer-models.spec.ts): tests/kicad/occ-export.spec.ts — dialog-driven export; asserts occ_service is fetched lazily (not on first load, once on export), the download's bytes validate (STEP ISO-10303-21 + deep-parse via an occt-import-js devDependency; magic-byte smoke for GLB/BREP/XAO/PLY/STL), and the UI stays responsive mid-export. tests/kicad/occ-import.spec.ts — cold-cache 3D view of a board with library models; asserts the model fetch + occ_service fetch both happen and components render (screenshot). Fixtures come from the existing 3d-viewer-models board; extra .step fixtures may be fetched from the models CDN and committed under tests/.
• Benchmarks (main vs post-Stage-3; same machine, committed BINARYEN_OPT_LEVEL; fill §6):
  • Raw sizes only (no gzip/brotli measuring): pcbnew.wasm (+ .js glue), occ_service.wasm, footprint_editor.wasm (byte-dup of pcbnew).
  • Build time: wall-clock ./docker/build.sh pcbnew, plus the occ_service build.
  • Build RAM: peak RSS of the post-link wasm-opt/apply-asyncify.sh steps (GNU time) — asyncify peaks ~8.3 GB today; release-config wasm-opt OOMs >64 GB; check whether the lean module fits release builds back under 64 GB.

6. Results

Metric	main	after split
pcbnew.wasm raw	146.7 MB (153,787,939 B)	103.4 MB (103,378,614 B) — −29.6%
footprint_editor.wasm raw	~146.7 MB (byte-dup)	103.4 MB (103,378,688 B)
kicad_editor.wasm raw (merged, post-unification)	~190 MB (CI, OCC-linked)	130.0 MB (136,282,145 B)
occ_service.wasm raw (lazy)	n/a	57.0 MB (57,037,715 B) (+ 0.28 MB glue)

The kicad_editor row is the post-rebase state (editor-unification Part 2 merged pcbnew+eeschema into ONE bundle): the split carries over structurally — the OCC gates live on pcbnew_kiface_objects / 3d-viewer, which is exactly what the merged target links via PCBNEW_KIFACE_LIBRARIES — so the merged image is OCC-free with no extra wiring (zero OCC type-registration strings in the shipped wasm; positive control occ_service.wasm has 35).

Clean-KiCad build benchmark (2026-07-02, same machine, sequential/idle, --clean-kicad, deps + ccache warm on both sides; container mem sampled at 5 s):

Stage	old pcbnew (main)	new pcbnew	occ_service
kicad-configure	131 s	28 s	32 s
kicad-compile + link	160 s	37 s	110 s (incl. in-container -Oz DCE + finalize)
finalize (host)	5 s	3 s	—
post-link stage (hoist + --asyncify + wasm-opt -O1, host)	106 s	55 s (−48%)	— (ASYNCIFY=0)
total wall	449.7 s	185.7 s	159.2 s
host peak RSS (post-processing)	10.28 GiB	6.74 GiB (−35%)	0.05 GiB
container mem peak (compile/link)	8.87 GiB	6.01 GiB	6.81 GiB

The race: old pcbnew 449.7 s vs new pcbnew + occ_service 344.9 s (−23%) — and the two new-side builds are independent (parallelizable in CI). Caveats: the worktree container's ccache was hotter (it had compiled these sources several times that day), which flatters the new side's configure/compile numbers; the post-link stage and RSS numbers are input-size-driven and ccache-independent — those are the structural wins. Per-pass wasm-opt splits only appear on Linux (GNU time -v); on macOS the post-link stage is timed as one unit.

OCC symbol check: zero libTK*/StepAP214/BRepBuilderAPI strings in the shipped pcbnew.wasm; the asyncify removelist's OCC patterns now warn "non-matching" (nothing left to match).

Node unit (2026-07-02): occExport → valid ISO-10303-21 STEP (60,628 B) in 274 ms incl. per-model desktop-parity warn+skip reporting; occLoadModel round-trips that STEP into a 199,971 B scenegraph cache in 124 ms; boot 146 ms.

E2e (2026-07-02, final binaries, ALL apps built): full suite 138 passed / 6 skipped / 0 failed / 0 flaky — every kicad spec × Firefox+Chromium, including occ-export (lazy-fetch boundary + dialog-driven STEP download), occ-probe, 3d-viewer-models (hard oce Load ok worker-parse assertion + render), and 3d-viewer-deadlock. Chromium probe exports the demo board in 1.3 s.

Standalone + demo app (2026-07-02, live dev servers, headless Chromium): the real web provider passes end to end in both modes. Plain dev — full dialog click-through (File → Export → STEP dialog → Export) fetches occ_service.{js,wasm} only on the Export click and lands a browser download export.step (60,628 B, ISO-10303-21), byte-identical to the Node unit; loadModel parses a 700,618 B STEP into a 569,097 B scenegraph cache in 2.1 s including worker boot. Demo mode (dev-demo.mjs, CDN libs + models): the demo board's .wrl models resolve through the still-static VRML plugin and occ_service is correctly never fetched — the lazy boundary holds for VRML-only boards. (The cold-cache "Failed to retrieve file times" modal that demo mode pops while models download is the 3D-models pipeline's stat-before-ensure behavior — reproduced identically on a main checkout with OCC-linked pcbnew, i.e. independent of this split.)

Validated against desktop kicad-cli 10.0.4 (2026-07-03, user's install; neutral referee = occt-import-js tessellating both files): geometric exact equality — identical mesh/triangle counts, bbox Δ = 0.00 µm, volume Δ = 0.0000% — across 3 boards (demo / pic_programmer / openair body-only) and option sweeps (copper stack, silk+mask, components-on skip-parity), for STEP, GLB, STL, BREP and STPZ; PLY/XAO structurally identical (sizes within dozens of bytes); U3D same-size/same-structure with only quantizer float-LSB byte differences (deterministic on both sides; its input tessellation is proven identical by the STL result); 3D-PDF structurally equal (0.02% size delta = embedded timestamps). Desktop runs OCC 7.9 vs our wasm OCC 7.8 — equality across different OCC versions. Our worker was also faster per export than the CLI. The comparison surfaced exactly one gap — the GLB writer flag, §7 — now fixed and guarded by occ-probe's 9-format matrix (step/stpz/brep/xao/ply/stl/glb/u3d/ pdf, magic + size asserted through the real worker).

Post-unification rerun (2026-07-02, after rebasing onto editor-unification Part 2 — the four editors now ship as the ONE merged kicad_editor bundle): full kicad suite 74 passed / 3 skipped / 0 failed / 0 flaky on Firefox (2.3 m) AND Chromium (12.2 m) — including occ-export/occ-probe, 3d-viewer-models (STEP parse through the worker) and xface-probe (the cross-face path that motivated installing the occ provider whenever the kicad_editor bundle boots, not just for the PCB tools). Standalone reruns on the live dev server: dialog click-through → lazy occ_service fetch → browser download export.step (60,628 B, ISO-10303-21, byte-identical to the Node unit); loadModel 700,618 B STEP → 569,097 B cache in 1.6 s incl. worker boot.

---

7. Risks / notes

• OCC writer toolkits (RESOLVED 2026-07-03): the toolkits were all built, but OCC's glTF/GLB writer compiles itself out without RapidJSON (-DUSE_RAPIDJSON=OFF → runtime "glTF writer is unavailable [HAVE_RAPIDJSON undefined]") — found by the kicad-cli comparison, invisible to the then-STEP-only e2e. Fixed by building OCC against the same RapidJSON official KiCad uses (kicad's vcpkg.json pulls opencascade's rapidjson feature): the vcpkg-pinned master snapshot 2025-02-26 (24b5e7a8b27f42fa16b96fc70aade9106cf7102f). RapidJSON's latest release tag (v1.1.0, 2016) is ill-formed under modern clang (GenericStringRef::operator= assigns const members — upstream issue #2347) and is not what any current KiCad build consumes. Regression net: occ-probe's 9-format matrix.
• DCE efficacy: if link-time -Oz leaves the service fat, use the $<TARGET_OBJECTS>→STATIC-archive fallback (§4 Stage 1). Measure first.
• Import parity: SCENEGRAPH must survive WriteCache→ReadCache byte-exactly enough for identical renders — it's KiCad's own on-disk cache format, used for exactly this purpose; screenshot gate confirms.
• Malformed STEP: OCCT throws Standard_Failure inside the worker; occLoadModel catches and returns empty → the existing per-model skip behavior (the registry's exception barrier stays as a second net).
• Threading (RESOLVED — two load-bearing pieces): the service needs the 2N+8 pre-warmed pthread pool (inherited from build-kicad-target.sh's PTHREAD_POOL_EXPR, the raytrace-deadlock fix 7630c7e) AND the GetKiCadThreadPool() warm-up in its main(). Confirmed by a PTHREADS_DEBUG trace: during export the KiCad pool consumes N workers, then OCC spawns its own wave (a launcher + N/2 workers) from a blocked context — a browser cannot create Workers on demand for a blocked thread, so with only N pre-warmed workers Chromium hangs forever inside EXPORTER_STEP (Firefox and Node happened to tolerate it; Chromium e2e caught it). Don't shrink the pool.
• Headless bootstrap in the worker (SETTINGS_MANAGER/locale/ADVANCED_CFG) mirrors sym_convert + the scripting-helpers pattern; budget for pcbnew-specific singletons.
• Asyncify-EH caveat: don't rely on RAII/try-catch cleanup on the pcbnew side across the suspend (asyncify-eh-unwind-landing-pads-unreliable); the happy path is proven by clipboard/fonts/pcbjam_fp/EnsureModelFile.
• Shadow ↔ header fidelity: the shadows must track exporter_step.h and the oce3d_* surface across KiCad rebases; drift surfaces as link errors (the good failure mode).
• Coordination: the import path relocates where oce3d_Load executes — same code, worker address space; owner of the 3D-models feature should know.
• Deploy: the live R2 wasm manifest carries no occ_service entry, so manifest-mode runs (dev-demo --wasm r2, the deployed demo) fail occ requests with no WASM version for "occ_service" until the next publish (publish-wasm.mjs already lists the tool and its no-shared-files layout); the split editor build must ship together with its occ_service folder.
• IGES export is behind #ifdef SUPPORTS_IGES (step_pcb_model.h:250), not in the dialog — out of scope. (IGES import works through oce3d_Load like STEP.)

---

8. Follow-ons (out of scope for v1)

• Full component embedding in exports: stage referenced model files into the worker (they're fetchable now via the models CDN pipeline) instead of warn+skip.
• VRML in numbers: if legacy .wrl project files turn out rare, s3d_plugin_vrml could also move to the service; if common, it stays (it's small and OCC-free).
• AddPadShape command-stream refactor (step_pcb_model.h:105): would shrink the service by dropping the board-model/parser duplication; touches KiCad core → deferred.
• Other pull-out candidates (bundle-size research, ranked): GAL bitmap font atlas ~3.0 MiB + newstroke font ~2.2 MiB (externalize as fetched assets — best value-per-effort after OCC); resident foreign importers (extend the existing NOT EMSCRIPTEN gate); protobuf looks dead but is load-bearing via EDA_ITEM : SERIALIZABLE — trap, skip.

---

Sources

• External: andymai/occt-wasm · kovacsv/occt-import-js · donalffons/opencascade.js.
• Dynamic-linking RED analysis + bundle composition: docs/features/perf/bundle-size.md (bundle-size branch; emscripten #13049, #17078, #19034, #19848, #22285).
• Import path: 3d-viewer/3d_cache/{pcbjam_static_3d_plugins,pcbjam_model_fetch,3d_cache}.cpp, plugins/3d/{oce,vrml}/CMakeLists.txt, plugins/3d/oce/loadmodel.cpp, web/standalone/src/wasm/libs/models-{source,bridge}.ts, tests/kicad/3d-viewer-models.spec.ts, plugins/3dapi/ifsg_api.h (Write/ReadCache).
• Export path: pcbnew/dialogs/dialog_export_step.cpp:548-708, pcbnew_jobs_handler.cpp:532-656, common/jobs/job_export_pcb_3d.cpp:94-149, pcbnew/exporters/step/*.
• Build template: eeschema/CMakeLists.txt:796-830, wasm/cli/sym_convert_main.cpp, scripts/kicad/build-kicad-target.sh, docker/build.sh. Headless load: pcbnew/python/scripting/pcbnew_scripting_helpers.cpp:96-235.
• Web plumbing: web/standalone/src/wasm/{boot.ts,wasm-assets.ts,libs/source.ts}, web/standalone/src/lib/download.ts:6, site/public/gerber-demo/boot.js.