Render project fonts in editor

[nighca]

Background

The project-font persistence and default-project foundation is tracked by #3343. Once a project carries font files and fontPreferences, XBuilder's editor must use the same font semantics when it renders SVG costumes, backdrops, and other image assets.

Draft PR #3367 implements the current editor-side integration. Its original data-URI approach was functionally correct but made large-font SVG previews prohibitively slow, so it cannot merge until the rendering strategy is improved.

Goal

Make editor image rendering consume project fonts and font preferences correctly and performantly, so editor preview aligns with project/runtime font semantics.

Scope

• Provide the current project's font files and ordered fontPreferences to SVG/image rendering consumers.
• Apply project font semantics to SVG font-family references and project fallback preferences.
• Embed or otherwise make available only the font resources required to render each image, without modifying the source SVG file.
• Replace the current large-font data-URI strategy with a performant approach.
• Verify rendering fidelity for the SVG features used by Builder assets.
• Add focused rendering, cache, and performance/regression coverage for the chosen solution.

Out of scope

• Project-font persistence, default-project assembly, and legacy-project migration; tracked by Implement project-font persistence and defaults in XBuilder #3343.
• Product UI for managing project font collections or preferences.

Related

• Parent tracking issue: Track project-level font support #3342
• Depends on the project-font foundation in Implement project-font persistence and defaults in XBuilder #3343.
• Implementation PR: feat: render project fonts in editor #3367.

[nighca]

Exploration status

Confirmed constraints

• Embedding a project font as a base64 data URI works for an SVG used through HTML Image / Konva, but it duplicates the complete font in every derived SVG. With a roughly 20 MiB Chinese font, loading and rendering an in-memory SVG takes about 600–700 ms even on a high-performance development MacBook Air.
• A blob: URL for the font does not work when that SVG is used as an image. SVG-as-image uses the restricted image processing mode, where external resources are disabled; the handwriting-font POC therefore fell back instead of using the blob: font. This is not merely a Blob lifetime or CORS issue. SVG processing modes
• An SVG embedded inline in the host document can use a blob: font, but standard browser APIs do not provide a way to turn the rendered live SVGSVGElement / arbitrary DOM into a bitmap. canvas.drawImage() accepts image sources, not a root <svg> element. Serializing that SVG back into a Blob and loading it as an image returns to the restricted SVG-as-image mode. Canvas image sources

Directions worth validating

1. WASM SVG renderer (recommended first POC): render an SVG using project font buffers (for example, Resvg/WASM) to PNG or ImageBitmap, ideally in a worker. This avoids repeating the font payload in every SVG and gives image/Konva a conventional bitmap source. Verify fidelity against the SVG features used by Builder assets before adopting it.
2. Font subsetting: convert to WOFF2 and embed only glyphs referenced by each SVG. This retains native SVG rendering but adds subsetting infrastructure and may still be costly for large or frequently changing text.
3. Import-time text-to-path conversion: eliminates runtime font loading, but changes editability/semantics and is likely only appropriate for an explicit conversion flow.
4. Render image assets as inline SVG in the editor: use DOM <svg> elements for costumes, backdrops, and similar images, allowing their fonts to remain ordinary blob:-backed web fonts. This avoids SVG-as-image restrictions, but the migration cost is high: StageViewer and MapViewer are currently based on Konva/canvas, so layering, transforms, hit testing, viewport behavior, and the existing canvas rendering path would all need reconsideration.
5. HTML-in-Canvas: WICG/html-in-canvas proposes rendering DOM children into canvas with APIs such as drawElementImage() and captureElementImage(). If standardized and broadly implemented, it could combine DOM/SVG font rendering with a canvas-based editor. It is not currently a viable product dependency: the repository describes it as a living explainer, and the APIs are only available behind Chromium's canvas-draw-element flag. It is worth monitoring, but not basing an implementation on today.

Resvg/WASM POC

• Browser POC using @resvg/resvg-wasm successfully loads project font buffers and renders an SVG to a PNG Blob usable by HTMLImageElement/Konva. The package's WASM payload is about 2.48 MiB.
• On a development MacBook Air, a 960×400 test SVG with the SPX default and basic-chinese fonts plus Handlee took about 78 ms to initialize WASM, 31 ms to load fonts, 39 ms to rasterize, and 15 ms to encode a 44 KiB PNG. These timings are promising relative to parsing/rendering a large-font data-URI SVG.
• Semantic blocker: Resvg loads fontBuffers by each file's internal font family name; it does not expose a project-name alias mapping. A test project font named Handwriting whose file has internal family Handlee fell back to sans-serif, while font-family="Handlee" rendered correctly. An SVG @font-face rule using local("Handlee") did not establish the alias either.
• Adopting this renderer therefore requires an explicit, reliable mapping from a project font name to the file's internal family name (or an equivalent font-name rewrite). Buffer ordering must not be used as an implicit substitute because it cannot preserve SVG/project font-family semantics when multiple fonts are present.

No implementation choice has been made yet. The immediate next step is to decide whether the alias mapping can become part of the project-font model/import path, then validate Resvg fidelity against representative Builder SVG assets.

[nighca]

Resvg/WASM POC: font-fallback fidelity blocker

The POC successfully rasterizes SVGs from project font buffers, avoiding the per-SVG large-font data-URI cost. It also maps a project family name to the exact loaded font face, so project names do not need to equal a font file's internal family name.

However, the current usvg 0.47 text fallback implementation cannot meet the project-font requirement that fallback happen at grapheme-cluster granularity.

Reproduction

The ProjectFonts test project declares:

"fontPreferences": ["Pixel", "Heart Emoji", "basic-chinese", "default"]

and includes all three project font families. Its SVG has both:

<text>ABC ❤️ 中文</text>
<text>A❤️B  Cafe&#x0301;  👩‍💻</text>

The explicit Scratch, "basic-chinese" text correctly renders Chinese. In contrast, the global text renders ABC ❤️ □□, and the extended-cluster text drops the heart and the ZWJ emoji.

The Chinese failure and emoji failure share one root cause. usvg re-shapes the full text with each fallback font, then currently aborts when the primary and fallback shaping results have different glyph counts. In this example, Pixel produces an additional glyph for the heart variation selector while basic-chinese does not; therefore the fallback pass that could supply Chinese is discarded. This is the same index-based merge limitation that prevents ZWJ/variation-selector emoji from falling back as whole clusters.

Upstream status

Upstream has an exact, but currently unmerged, fix:

• linebender/resvg#861 documents the compound/ZWJ emoji failure.
• linebender/resvg#1087 replaces the index-based merge with shared cluster-boundary merging and explicitly implements usvg's Replace clusters and not glyphs TODO.

The PR was opened on 2026-06-28 (after the equivalent #1071 was auto-closed when its author deleted a fork). Its CI is green, but it has no review, comment, assignee, label, or post-open update as of 2026-07-24. We should not rely on an imminent upstream merge.

Decision implication

The current WASM implementation is promising for performance but must remain draft: it does not yet provide the required editor/runtime rendering fidelity. The next implementation decision is whether to vendor/adapt the upstream cluster-merge change, wait for an upstream release, or choose a different editor rendering path.