perf(mobile): canvas mount causes severe main-thread hang when opening a .canvas file

[LeslieOA]

Context

Profiled on iPhone 16 Pro (A18 Pro), iOS 26.4.1. Release build, Xcode Instruments "Animation Hitches" template in Deferred mode. Trace covers cold launch → file picker → canvas open → pinch gestures (~35s total).

Profiling caveat: Deferred-mode Instruments adds non-trivial overhead. The hang duration reported below is an upper bound. Without Instruments attached, the canvas "feels a little jumpy on first appear" — there's a perceptible hitch but it's less dramatic than the trace suggests. The trace's value is in identifying the blocking work, not the exact duration.

Observation

Instruments flagged a Severe Hang (>500ms main-thread block) when a .canvas file is selected from the picker and the canvas view mounts. The hang manifests as both a Hang event and multiple single-frame hitches in the trace. This corresponds to the user-perceptible "jumpy" feeling when the canvas first appears — a burst of dropped frames followed by smooth rendering once the canvas settles.

Hypotheses

These are starting points for investigation, not conclusions:

1. Synchronous image decoding via useImage. If image nodes call useImage eagerly on mount, every image node — including those outside the viewport — may trigger synchronous decode before viewport culling has had a chance to exclude them.

2. JSON Canvas parsing on the JS thread. File read + JSON parse + node tree construction may all be happening synchronously within a single JS frame, producing a long task that blocks the main thread bridge.

3. Full layout pass before culling. If all 20–50 nodes go through an initial layout pass before the viewport culling logic runs, that's a lot of unnecessary measurement work on the first frame.

4. Reanimated shared value initialisation. Camera transform setup (pan offset, zoom scale, decay animations) initialises multiple shared values; if these trigger synchronous UI-thread work during mount, they contribute to the hang.

Suggested investigation

• Add os_signpost markers around: file read, JSON parse, node tree construction, and first render pass to identify which phase dominates.
• Check whether useImage calls block the JS thread or fire asynchronously — if they're awaited or synchronous, they're part of the hang.
• Verify that viewport culling runs before the first render, not as a post-render effect that prunes on the second frame.
• Consider deferring non-visible node mounting behind InteractionManager.runAfterInteractions or a requestAnimationFrame boundary so the canvas shell appears immediately and nodes populate progressively.

Acceptance criteria

Opening a canvas with 50 nodes produces no Hang event (>100ms main-thread block) in a clean Instruments trace, and feels visually smooth (no jumpy first frames) in normal use on iPhone 16 Pro.

Related

• workspace-sh/workspace#76 — Instruments profiling for canvas rendering during gestures
• workspace-sh/workspace#75 — rasterise-during-gesture optimisation
• workspace-sh/workspace#79 — picker presentation hitch (filed alongside this issue)

[LeslieOA]

Status: moved from In Progress → Todo to reflect actual state — there's no open PR addressing this. The issue captures Instruments findings ready for pickup, not work in flight.

Related

• workspace-sh/workspace#76 (closed) — the profiling session that surfaced this hang
• workspace-sh/workspace#79 — picker presentation hitch from the same trace
• workspace-sh/workspace#75 (closed, PR workspace-sh/workspace#83) — Picture recording lands on top of this; mount hang is separate
• workspace-sh/workspace#39 (closed, PR workspace-sh/workspace#77) — viewport culling is one of the hypothesised mitigations to test

[LeslieOA]

On-device verification of the parse-cache slice (#62, merged): tested via Workspace mobile (real consuming app, symlinked to library src/) opening Cards.canvas (61 text nodes, all markdown). Cold first-open feels responsive; markdown correctness intact (bold/italic/code/headings/lists/callout zones); pinch-zoom smooth (Picture-path drawTextNode now hits the cache instead of re-parsing).

#62 removes duplicate parses (React tree + Picture pass + callout zones → one parse per unique string). The first parse of each unique node on cold open is still paid — that's the remaining, larger lever tracked here: progressive / deferred node mounting so the canvas shell appears immediately and nodes populate without a synchronous burst. Still open.

[LeslieOA]

Before anyone picks up the remaining work here: the Instruments trace this issue is built on predates #35, which extended the Picture overlay and viewport culling to camera animations. Together with the parse cache from #62 (verified on-device in the comment above), the mount-time profile has likely shifted meaningfully since the original capture — hypotheses 1 and 3 in particular (eager useImage decode outside the viewport; full layout pass before culling) were written against the pre-#35 culling behaviour.

Recommendation: re-profile with Xcode Instruments (same setup — release build, Animation Hitches template, deferred mode, cold launch → picker → canvas open) before doing further optimisation work, so effort targets the current bottleneck rather than the historical one. The acceptance criterion (no >100ms Hang event opening a 50-node canvas) still stands and is the thing to measure; it is possible #35 + #62 already moved the needle enough to change which hypothesis dominates — or to close this outright.

If the hang persists, the os_signpost markers suggested in the body remain the right first step, and the progressive/deferred node mounting identified in the #62 follow-up comment is the leading candidate. But measure first.