Skip to content

fix(uikit): ship a bundled MSDF worker so TTFLoader works in production builds - #267

Open
felixtrz wants to merge 1 commit into
pmndrs:mainfrom
felixtrz:fix/msdf-worker-bundling
Open

felixtrz wants to merge 1 commit into
pmndrs:mainfrom
felixtrz:fix/msdf-worker-bundling

Conversation

@felixtrz

@felixtrz felixtrz commented Aug 2, 2026

Copy link
Copy Markdown
Contributor

The problem

TTFLoader calls new MSDF() with no arguments, so @zappar/msdf-generator falls back to its own defaults for both the worker and the wasm. Neither survives a bundler.

The worker. It ships as unbundled ESM containing a bare import { expose, transfer } from 'comlink', and the package builds its worker URL in the MSDF constructor — separate from the new Worker(url, { type: 'module' }) that consumes it:

// @zappar/msdf-generator/dist/index.js
this.workerUrl = config.workerUrl || new URL('./worker.js', import.meta.url).href   // line 33
this.worker = new Worker(workerUrl, { type: 'module' })                             // line 8

Bundlers only bundle a worker when both halves are visible in a single expression. Split like this, the file is copied through verbatim instead — and a module worker cannot resolve a bare specifier, so it fails to load a few milliseconds after construction.

The wasm. Same problem in a second form: Emscripten names it with a runtime string through locateFile, so no bundler can see the dependency and it is never emitted.

Why it is hard to diagnose

Both failures are silent. A worker whose module graph fails to resolve fires an error event with an empty message, no filename and no line, and nothing reaches the console. The generator never initialises, so the caller's promise never settles. Downstream that reads as a blank canvas with a completely clean console.

No consumer configuration fixes it

I built a consuming app using the exact settings our own ttf examples carry — optimizeDeps.exclude: ['@zappar/msdf-generator'] plus assetsInclude: ['**/*.wasm'] — and the emitted worker still contained from "comlink" and the wasm was still not emitted.

Our examples do not catch this because they only have a dev script; nothing in examples/ is ever production-built.

The change

  • scripts/build-msdf-assets.mjs bundles the worker (inlining comlink) and copies the wasm.
  • TTFLoader points at those copies via new URL('./…', import.meta.url).href, the bundler-agnostic idiom.
  • Assets are written to src/loaders and dist/loaders, because this package resolves to src/index.ts inside the monorepo and only to dist/index.js once published (publishConfig), so import.meta.url in ttf.ts resolves against whichever is in play.

Verification

Measured against a WebXR app that reproduced the hang, with no build-side workaround in the app:

before after
World.create() never resolves resolves at 1432 ms
steady state 1 draw call/frame 617 draw calls/frame
msdfgen_wasm.wasm never emitted served once per font weight
404s / console errors none (silent) none

Notes for reviewers

  • Lockfile not included. Adding the esbuild devDependency needs a pnpm install, but my pnpm reformatted the entire pnpm-lock.yaml (~6250 lines of churn for ~4 real ones), so I left it out rather than bury the diff. Needs regenerating.
  • prepare script is how the src/loaders copies come to exist after install, which the examples need in dev. Happy to move it if you would rather it sat elsewhere in the pipeline.
  • Two output locations is the part I would most expect you to want done differently — a single location with a path shim would also work.
  • packages/uikit currently has 57 pre-existing tsc errors on main, unrelated to this change; tsc still emits, so the build completes.
  • The cleanest fix would be ~2 lines in @zappar/msdf-generator (inline the new Worker(new URL(...)) and default wasmUrl), but that package publishes to npm with no repository, homepage or bugs field and no public source I could find, so this seemed like the right layer.

…on builds

TTFLoader calls `new MSDF()` with no arguments, so @zappar/msdf-generator
falls back to its own defaults for the worker and the wasm. Neither
survives a bundler.

The worker is shipped as unbundled ESM containing a bare
`import { expose, transfer } from 'comlink'`, and the package builds its
worker URL in the MSDF constructor, separate from the
`new Worker(url, { type: 'module' })` that consumes it. Bundlers only
bundle a worker when both halves are visible in one expression, so the
file is copied through verbatim instead — and a module worker cannot
resolve a bare specifier, so it fails to load a few milliseconds after
construction. The wasm is the same problem in a second form: Emscripten
names it with a runtime string through locateFile, so no bundler can see
that dependency and it is never emitted.

Both failures are silent. A worker whose module graph fails to resolve
fires an error event with an empty message, no filename and no line, so
nothing reaches the console; the generator simply never initialises and
the caller's promise never settles. Downstream that reads as a blank
canvas with a clean console, which is a hard thing to chase.

No consumer configuration fixes this. Building a consuming app with the
settings our own ttf examples use — optimizeDeps.exclude on
@zappar/msdf-generator plus assetsInclude for wasm — still emits the
worker with its bare import and still omits the wasm. The examples do not
catch it because they only have a dev script; nothing here is ever
production-built.

So bundle the worker into this package and ship the wasm beside it, then
point TTFLoader at copies it can address relatively, which every bundler
understands. The assets are written to src/loaders as well as
dist/loaders because this package resolves to src/index.ts inside the
monorepo and only to dist/index.js once published, so import.meta.url in
ttf.ts resolves against whichever is in play.

Verified against a WebXR app that reproduced the hang: with this change
and no build-side workaround, its World.create() promise resolves in
1432ms and the scene renders at 617 draw calls per frame, with the wasm
served once per font weight and no 404s. Before it never resolved at all.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant