fix(plugins): pause and suspend plugin frames when they leave the screen

A tester reported that their own plugin, fine on the web, slowed the app down
badly on a phone. A sandboxed plugin iframe keeps running its timers, polling and
animation even off screen, and on a phone it shares the WebView's main thread with
the whole app, so a heavy one janks everything.

The frame now watches whether it is on screen and the app in the foreground
(IntersectionObserver + page visibility) and forwards it as trek:visibility, so a
plugin can pause its work while hidden; the design kit exposes trek.onVisibility /
trek.isVisible and pauses its own CSS animations via data-hidden. On a phone a
dashboard-widget plugin scrolled well out of view is suspended outright: its iframe
is unmounted and a placeholder holds the widget's height, so an offscreen widget
costs nothing and remounts when it scrolls back.
This commit is contained in:
Maurice
2026-11-15 20:33:27 +01:00
parent a58d0117c6
commit c4a2a91578
4 changed files with 177 additions and 27 deletions
@@ -939,3 +939,58 @@ describe('PluginFrame', () => {
});
});
});
// FE-PLUGINS-FRAME-062 to 063: visibility lifecycle + phone off-screen suspend.
// A heavy plugin that keeps working off screen bogs down the shared WebView on a
// phone (reported via TestFlight), so the frame tells the plugin when it is hidden
// and, for a phone dashboard widget, unmounts the iframe entirely while off screen.
describe('PluginFrame visibility and mobile suspend', () => {
let ios: Array<{ cb: IntersectionObserverCallback }>;
let realIO: unknown;
let realMM: typeof window.matchMedia;
beforeEach(() => {
ios = [];
realIO = (window as unknown as { IntersectionObserver: unknown }).IntersectionObserver;
realMM = window.matchMedia;
class IO {
cb: IntersectionObserverCallback;
constructor(cb: IntersectionObserverCallback) { this.cb = cb; ios.push({ cb }); }
observe() {} unobserve() {} disconnect() {} takeRecords() { return []; }
}
(window as unknown as { IntersectionObserver: unknown }).IntersectionObserver = IO as unknown;
});
afterEach(() => {
(window as unknown as { IntersectionObserver: unknown }).IntersectionObserver = realIO;
window.matchMedia = realMM;
cleanup();
});
const asPhone = () => {
window.matchMedia = ((q: string) => ({
matches: true, media: q, onchange: null,
addEventListener() {}, removeEventListener() {}, addListener() {}, removeListener() {}, dispatchEvent() { return false; },
})) as unknown as typeof window.matchMedia;
};
const fire = (intersecting: boolean) =>
act(() => { ios[ios.length - 1].cb([{ isIntersecting: intersecting } as IntersectionObserverEntry], {} as IntersectionObserver); });
it('FE-PLUGINS-FRAME-062: tells the plugin when it leaves the screen', () => {
const { container } = render(<PluginFrame pluginId="demo" surface="dashboard-widget" />);
const iframe = container.querySelector('iframe')!;
const posted: Array<Record<string, unknown>> = [];
(iframe.contentWindow as unknown as { postMessage: (m: unknown) => void }).postMessage = (m) => posted.push(m as Record<string, unknown>);
fire(false);
expect(posted.find((m) => m.type === 'trek:visibility')).toMatchObject({ visible: false });
fire(true);
expect(posted.filter((m) => m.type === 'trek:visibility').pop()).toMatchObject({ visible: true });
});
it('FE-PLUGINS-FRAME-063: suspends a phone dashboard widget off screen and brings it back', () => {
asPhone();
const { container } = render(<PluginFrame pluginId="demo" surface="dashboard-widget" />);
expect(container.querySelector('iframe')).toBeTruthy();
fire(false);
expect(container.querySelector('iframe')).toBeNull();
fire(true);
expect(container.querySelector('iframe')).toBeTruthy();
});
});
+103 -26
View File
@@ -320,6 +320,16 @@ export default function PluginFrame({ pluginId, tripId = null, placeId = null, d
const tripCurrency = useTripStore((s) => s.trip?.currency)
const displayCurrency = (settings.default_currency || tripCurrency || 'EUR').toUpperCase()
const [height, setHeight] = useState<number | null>(null)
// Lifecycle: tell a plugin when it is off the screen or the app is backgrounded,
// so a heavy one can pause its timers, polling and animation instead of burning
// the shared main thread (worst on a phone, where the whole app janks). And on a
// phone a dashboard-widget plugin scrolled well out of view is suspended outright
// — its iframe is unmounted and a placeholder keeps its height — so an offscreen
// widget costs nothing and comes back on its own when it scrolls into view.
const wrapRef = useRef<HTMLDivElement | null>(null)
const visibleRef = useRef(true)
const [suspended, setSuspended] = useState(false)
const suspendable = isPhone && surface === 'dashboard-widget'
// A host-rendered ConfirmDialog on the plugin's behalf: sandboxed frames have no
// allow-modals and can't overlay the host, so destructive plugin actions get the
// same native confirm every TREK feature uses. One at a time; extras are refused.
@@ -670,6 +680,56 @@ export default function PluginFrame({ pluginId, tripId = null, placeId = null, d
}
}, [pluginId])
// Watch whether the frame is on screen (and the tab/app in the foreground) and
// forward it to the plugin as `trek:visibility`; on a phone, a dashboard widget
// that leaves the screen (with a margin so a partial scroll never tears it down)
// is suspended, which unmounts the heavy iframe entirely.
useEffect(() => {
// A phone widget keeps the wrapper mounted across a suspend and is observed
// there; everything else is observed on the iframe itself, which never unmounts.
const el = suspendable ? wrapRef.current : frameRef.current
if (!el || typeof IntersectionObserver === 'undefined') return
let onscreen = true
const emit = () => {
const visible = onscreen && !document.hidden
if (visible !== visibleRef.current) {
visibleRef.current = visible
postFrame({ type: 'trek:visibility', visible })
}
}
const io = new IntersectionObserver(
(entries) => {
onscreen = entries[entries.length - 1]?.isIntersecting ?? true
emit()
if (suspendable) setSuspended(!onscreen)
},
{ rootMargin: suspendable ? '250px 0px' : '0px', threshold: 0 }
)
io.observe(el)
const onVis = () => emit()
document.addEventListener('visibilitychange', onVis)
return () => {
io.disconnect()
document.removeEventListener('visibilitychange', onVis)
}
}, [pluginId, postFrame, suspendable])
// Coming back from a suspend remounts a fresh iframe (same pluginId key), so the
// load counter has to start over or the remount reads as a self-navigation and
// never gets the context; going into one stops the geolocation watch of the frame
// that is about to be unmounted.
useEffect(() => {
if (suspended) {
if (geoWatchRef.current != null) {
navigator.geolocation.clearWatch(geoWatchRef.current)
geoWatchRef.current = null
}
} else {
loadsRef.current = 0
visibleRef.current = true
}
}, [suspended])
const answerConfirm = (confirmed: boolean) => {
const req = confirmReqRef.current
if (req) postFrame({ type: 'trek:confirm:result', requestId: req.requestId, confirmed })
@@ -682,36 +742,53 @@ export default function PluginFrame({ pluginId, tripId = null, placeId = null, d
const pluginLabel = title || pluginId
const confirmTitle = confirmReq?.title ? `${pluginLabel} — ${confirmReq.title}` : pluginLabel
const pluginFrame = (
<iframe
key={pluginId}
ref={frameRef}
src={`/plugin-frame/${pluginId}/${path}`}
// Deliver the context as soon as the document is parsed (the plugin sets up its
// message listener during parse), closing the trek:ready race so the theme is
// right on first paint. A 2nd load is a self-navigation — don't bridge to it.
onLoad={() => {
setLoadFailed(false)
loadsRef.current += 1
if (loadsRef.current === 1) {
postFrame(buildContext())
// A widget that loaded off screen (or a backgrounded app) learns so at once,
// so it never starts its work just to be told to stop a frame later.
if (!visibleRef.current) postFrame({ type: 'trek:visibility', visible: false })
}
// A self-navigated frame is no longer bridged, so its watch is only
// burning battery for positions nobody receives.
else if (geoWatchRef.current != null) { navigator.geolocation.clearWatch(geoWatchRef.current); geoWatchRef.current = null }
}}
onError={() => setLoadFailed(true)}
sandbox="allow-scripts allow-forms"
allowFullScreen
allow="fullscreen"
referrerPolicy="no-referrer"
loading="lazy"
title={title || pluginId}
className={className}
style={{ width: '100%', height: suspendable ? '100%' : fill ? '100%' : height ?? '100%', border: 0, display: loadFailed ? 'none' : undefined }}
/>
)
return (
// Third-party code: a throw in here must cost the plugin, not the page.
<ErrorBoundary boundaryId="plugin-frame" label={pluginLabel} resetKeys={[pluginId]}>
<>
<iframe
key={pluginId}
ref={frameRef}
src={`/plugin-frame/${pluginId}/${path}`}
// Deliver the context as soon as the document is parsed (the plugin sets up its
// message listener during parse), closing the trek:ready race so the theme is
// right on first paint. A 2nd load is a self-navigation — don't bridge to it.
onLoad={() => {
setLoadFailed(false)
loadsRef.current += 1
if (loadsRef.current === 1) postFrame(buildContext())
// A self-navigated frame is no longer bridged, so its watch is only
// burning battery for positions nobody receives.
else if (geoWatchRef.current != null) { navigator.geolocation.clearWatch(geoWatchRef.current); geoWatchRef.current = null }
}}
onError={() => setLoadFailed(true)}
sandbox="allow-scripts allow-forms"
allowFullScreen
allow="fullscreen"
referrerPolicy="no-referrer"
loading="lazy"
title={title || pluginId}
className={className}
style={{ width: '100%', height: fill ? '100%' : height ?? '100%', border: 0, display: loadFailed ? 'none' : undefined }}
/>
{loadFailed && (
{suspendable ? (
// Phone dashboard widget: the wrapper holds the widget's measured height so
// the list does not jump when the iframe is unmounted off screen.
<div ref={wrapRef} style={{ width: '100%', height: height ?? 160 }}>
{!suspended && pluginFrame}
</div>
) : (
pluginFrame
)}
{loadFailed && !suspended && (
<div
role="alert"
className="flex items-center justify-center rounded-xl border border-edge bg-surface-2 p-6 text-caption text-content-2"
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "trek-plugin-sdk",
"version": "1.9.0",
"version": "1.9.1",
"description": "SDK for building TREK plugins: types, definePlugin, a mock host, manifest validation, and the create-trek-plugin / trek-plugin CLIs.",
"type": "module",
"license": "MIT",
+18
View File
@@ -475,6 +475,8 @@ export const TREK_THEME_JS = `(function () {
var docEl = document.documentElement;
var ctxHandlers = [];
var evtHandlers = [];
var visHandlers = [];
var visible = true;
var lastCtx = null;
var pending = {};
var pendingConfirms = {};
@@ -555,6 +557,14 @@ export const TREK_THEME_JS = `(function () {
for (var w = 0; w < geoWatchers.length; w++) { try { geoWatchers[w](m.position || null, m.error || null); } catch (e) {} }
} else if (m.type === 'trek:event') {
for (var j = 0; j < evtHandlers.length; j++) { try { evtHandlers[j](m.event, m.tripId); } catch (e) {} }
} else if (m.type === 'trek:visibility') {
// The host tells us when this frame leaves the screen or the app goes to the
// background. Pause your timers, polling and animation here: a widget that keeps
// working off screen bogs down the shared WebView on a phone. data-hidden lets the
// kit CSS pause its own animations; onVisibility gets the plugin's own work.
visible = m.visible !== false;
setFlag('data-hidden', !visible);
for (var v = 0; v < visHandlers.length; v++) { try { visHandlers[v](visible); } catch (e) {} }
}
});
@@ -635,6 +645,14 @@ export const TREK_THEME_JS = `(function () {
if (lastCtx) { try { cb(lastCtx); } catch (e) {} }
return function () { var i = ctxHandlers.indexOf(cb); if (i >= 0) { ctxHandlers.splice(i, 1); } };
},
// Whether the frame is on screen and the app is in the foreground, and a hook for
// the changes. Use it to pause heavy work while hidden; isVisible() seeds the first
// run. Returns an unsubscribe.
isVisible: function () { return visible; },
onVisibility: function (cb) {
visHandlers.push(cb);
return function () { var i = visHandlers.indexOf(cb); if (i >= 0) { visHandlers.splice(i, 1); } };
},
notify: function (level, message, duration) { send({ type: 'trek:notify', level: level, message: message, duration: duration }); },
navigate: function (to) { send({ type: 'trek:navigate', to: to }); },
openExternal: function (url) { send({ type: 'trek:openExternal', url: url }); },