fix(canvas): load deep-linked canvases reliably + add manual Refresh

[raquelmsmith]

Problem

Clicking a deep link to a canvas after the app has been open for a while showed a blank canvas — it only appeared after a hard refresh of the app. There was also no way to manually reload a mounted canvas.

Why: Requested after canvases repeatedly failed to load from deep links on long-lived sessions, plus a desire to force-refresh a canvas on demand.

Root cause (not stale iframe content, despite the initial hunch): canvases render through a persistent warm-iframe pool that only makes a canvas visible once its slot has a measured on-screen rect. The route-level placeholder measured that rect in a layout effect but created its pool slot in a passive effect that ran afterwards, so the first measurement was dropped (the setter no-ops when the slot doesn't exist yet). On a still-settling layout (right after a hard refresh) a later resize/scroll re-measure filled the rect in; on an already-settled layout no such re-measure fired, so the rect stayed empty and the iframe never became visible.

Changes

• Deep-link load fix: register the canvas's pool slot in a layout effect ordered before the rect measurement, so the rect is populated deterministically on first commit and the canvas shows without a hard refresh. Guarded by a deterministic regression test (the jsdom ResizeObserver stub never fires, reproducing the "settled layout" condition).
• Manual Refresh: add a Refresh item to the canvas options (⋯) menu that fully remounts the mounted iframe element — not just reloads its document — so it also recovers from a wedged host-side/pool state, and invalidates the host-side canvas read cache so the reload fetches fresh data. Implemented as a per-slot "remount generation" folded into the frame's React key; it's keyed by slot index and bumped only by an explicit refresh, so navigation between canvases still reuses the warm frames (no reload).

How did you test this?

• pnpm --filter @posthog/ui typecheck — clean.
• biome lint on all touched files — clean.
• pnpm --filter @posthog/ui test — full suite passes (incl. new CanvasFramePlaceholder rect regression test and canvasFrameStore remount tests). Verified the rect test fails when the fix is reverted.
• Manual verification in the running app is still pending (needs the project-bluebird flag); steps: warm the pool by opening 2+ canvases, then open a canvas via deep link / navigation and confirm it renders without a hard refresh; and ⋯ → Refresh recreates the iframe (brief re-boot) and re-runs data queries.

Automatic notifications

• Publish to changelog?
• Alert Sales and Marketing teams?

---

Created with PostHog Code

[trunk-io]

😎 Merged successfully - details.

[github-actions]

React Doctor found no issues in the changed files. 🎉

_{Reviewed by React Doctor for commit bfd86f7.}

[greptile-apps]

_{Reviews (1): Last reviewed commit: "fix(canvas): load deep-linked canvases r..." | Re-trigger Greptile}

[github-actions]

Contained UI-layer bug fix with good test coverage. The useEffect→useLayoutEffect change correctly ensures the slot exists before the rect measurement runs, fixing the deep-link load regression. The frameKeys approach cleanly replaces the deleted canvasRefreshStore with no risk of silent state mismatch, and the Refresh action is purely additive.

[raquelmsmith]

/trunk merge