diff --git a/client/src/components/Plugins/PluginFrame.test.tsx b/client/src/components/Plugins/PluginFrame.test.tsx
index 151484793..dbf7d1eb1 100644
--- a/client/src/components/Plugins/PluginFrame.test.tsx
+++ b/client/src/components/Plugins/PluginFrame.test.tsx
@@ -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();
+ const iframe = container.querySelector('iframe')!;
+ const posted: Array> = [];
+ (iframe.contentWindow as unknown as { postMessage: (m: unknown) => void }).postMessage = (m) => posted.push(m as Record);
+ 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();
+ expect(container.querySelector('iframe')).toBeTruthy();
+ fire(false);
+ expect(container.querySelector('iframe')).toBeNull();
+ fire(true);
+ expect(container.querySelector('iframe')).toBeTruthy();
+ });
+});
diff --git a/client/src/components/Plugins/PluginFrame.tsx b/client/src/components/Plugins/PluginFrame.tsx
index 21f514780..f3410a089 100644
--- a/client/src/components/Plugins/PluginFrame.tsx
+++ b/client/src/components/Plugins/PluginFrame.tsx
@@ -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(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(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 = (
+