Keep immersive owner and mode atomic (#726)

Co-authored-by: hamzamerzic <10846014+hamzamerzic@users.noreply.github.com>
Co-authored-by: Möbius Agent <mobius-agent@users.noreply.github.com>

Author: hamzamerzic

frontend/public/mobius-runtime.js

@@ -3583,6 +3583,7 @@ const MOVE_TOL_PX = 10;
 function makeImmersive({ appId } = {}) {
 	let hidden = false;
 	const listeners = /* @__PURE__ */ new Set();
+	const holds = /* @__PURE__ */ new WeakMap();
 	const hasParent = typeof window !== "undefined" && window.parent && window.parent !== window;
 	function notify() {
 		for (const cb of [...listeners]) try {
@@ -3630,10 +3631,9 @@ function makeImmersive({ appId } = {}) {
 			listeners.delete(cb);
 		};
 	}
-	function holdToToggle(el, opts = {}) {
+	function holdToToggle(el) {
 		if (!el || typeof el.addEventListener !== "function") return () => {};
-		if (el.__mobiusHold) return el.__mobiusHold;
-		const holdMs = typeof opts.holdMs === "number" ? opts.holdMs : HOLD_MS;
+		if (holds.has(el)) return holds.get(el);
 		let timer = null;
 		let startX = 0;
 		let startY = 0;
@@ -3683,7 +3683,7 @@ function makeImmersive({ appId } = {}) {
 					if (navigator.vibrate) navigator.vibrate(10);
 				} catch (e2) {}
 				toggle();
-			}, holdMs);
+			}, HOLD_MS);
 		}
 		function onPointerMove(e) {
 			if (timer === null) return;
@@ -3709,7 +3709,7 @@ function makeImmersive({ appId } = {}) {
 		el.addEventListener("contextmenu", onContextMenu);
 		const cleanup = () => {
 			release();
-			delete el.__mobiusHold;
+			holds.delete(el);
 			el.style.cursor = prev.cursor;
 			el.style.touchAction = prev.touchAction;
 			el.style.userSelect = prev.userSelect;
@@ -3722,7 +3722,7 @@ function makeImmersive({ appId } = {}) {
 			el.removeEventListener("click", onClickCapture, true);
 			el.removeEventListener("contextmenu", onContextMenu);
 		};
-		el.__mobiusHold = cleanup;
+		holds.set(el, cleanup);
 		return cleanup;
 	}
 	return {

frontend/src/components/AppCanvas/AppCanvas.jsx

@@ -239,13 +239,10 @@ function CanvasLoadingBrand({ appName }) {
 const AppCanvas = forwardRef(function AppCanvas({
   appId, version = 0, appName, appSlug, offlineCapable = false,
   capabilityContract = null,
-  immersive = false,
-  // The lighter "look like a standalone app" collapse (mode:'bar'): the shell
-  // hides its toolbar but keeps the status-bar strip, so unlike `immersive`
-  // (full-bleed) the app is NOT painted under the notch and needs no safe-area
-  // insets. It still counts as "chrome hidden" for the app's immersive helper
-  // echo, so the app's toggle()/`.hidden` stay correct.
-  barCollapsed = false,
+  // The shell's applied presentation for this app: full-bleed immersive,
+  // status-bar-preserving chrome collapse, or null. One value keeps safe-area
+  // forwarding and the runtime echo from observing contradictory booleans.
+  immersiveMode = null,
   // Whether this app is the currently-visible canvas (canvas view + active
   // app). One prop, two consumers:
   //   - `moebius:frame-visibility` — the shell keeps recently-used apps
@@ -422,8 +419,8 @@ const AppCanvas = forwardRef(function AppCanvas({
   // listener is live and it can receive frame-init/theme/insets. Per frame,
   // because the two buffered frames finish loading independently.
   const loadedDocsRef = useRef(new Set())
-  // version -> last immersive intent (bool) that frame declared. Recorded for
-  // EVERY frame, including a hidden incoming one whose real-time immersive post
+  // version -> last immersive request ({ value, mode }) that frame declared.
+  // Recorded for every frame, including a hidden incoming one whose real-time post
   // is withheld (only the visible frame drives chrome live). On a swap we replay
   // the promoted frame's recorded intent so an immersive game stays immersive
   // across a rebuild without a chrome flash.
@@ -735,7 +732,7 @@ const AppCanvas = forwardRef(function AppCanvas({
         // from the verified source, never the payload — but the mode is a
         // harmless presentation hint the frame may choose.
         const mode = msg.mode === 'bar' ? 'bar' : 'full'
-        frameImmersiveRef.current.set(srcVersion, value)
+        frameImmersiveRef.current.set(srcVersion, { value, mode })
         if (srcVersion === liveVersionRef.current && activeRef.current) {
           onImmersive?.(appId, value, mode)
         }
@@ -986,13 +983,14 @@ const AppCanvas = forwardRef(function AppCanvas({
   useEffect(() => {
     if (!appId) return
     const current = { appId, liveVersion: swap.liveVersion, active }
+    const intent = frameImmersiveRef.current.get(swap.liveVersion)
     const value = immersiveLifecycleValue(
       immersiveLifecycleRef.current,
       current,
-      frameImmersiveRef.current.get(swap.liveVersion),
+      intent?.value,
     )
     immersiveLifecycleRef.current = current
-    if (value !== null) onImmersive?.(appId, value)
+    if (value !== null) onImmersive?.(appId, value, intent?.mode)
   }, [appId, swap.liveVersion, active, onImmersive])
 
   // Unmount/eviction is a hard release even when no active-state render landed.
@@ -1066,9 +1064,9 @@ const AppCanvas = forwardRef(function AppCanvas({
   // pad away from the notch/home-indicator. env(safe-area-inset-*) reads 0
   // inside the sandboxed iframe, so the shell reads the real values off a
   // probe element and posts them; the frame applies them to :root as
-  // --mobius-safe-*. Only non-zero while THIS app is immersive — a windowed
-  // app's chrome already owns the inset padding, so it must receive zeros and
-  // not double-pad. Sent on iframe load (sendInsets in onLoad), whenever the
+  // --mobius-safe-*. Only non-zero in full-bleed mode. Windowed and
+  // bar-collapsed apps keep shell-owned inset padding and receive zeros, so they
+  // cannot double-pad. Sent on iframe load (sendInsets in onLoad), whenever the
   // immersive verdict flips, and on resize/orientationchange while immersive
   // (a rotation moves the cutout, so the cached insets would otherwise go
   // stale — see the geometry-change effect below).
@@ -1077,22 +1075,23 @@ const AppCanvas = forwardRef(function AppCanvas({
   // windowed frame whose chrome already owns the inset padding also gets zeros
   // so it can't double-pad.
   function sendInsets(v) {
-    const insets = (v === liveVersionRef.current && immersive) ? readDeviceInsets() : zeroInsets()
+    const insets = (v === liveVersionRef.current && immersiveMode === 'full')
+      ? readDeviceInsets()
+      : zeroInsets()
     postToFrame(v, { type: 'moebius:frame-insets', insets })
   }
 
   // Echo the shell's APPLIED immersive verdict for this app so the runtime's
   // window.mobius.immersive helper stays authoritative — toggle()/`.hidden`
   // must reflect a release the shell made on its own (the floating exit button,
   // or an app switch that dropped the lease), not just the app's last request.
-  // The `immersive` prop is exactly that applied verdict (active canvas AND this
-  // app holds the lease). Only the live frame is the immersive holder, so a
+  // `immersiveMode` is exactly that applied verdict (active canvas AND this app
+  // holds the lease). Only the live frame is the immersive holder, so a
   // hidden/incoming buffered frame always learns `false`.
   function sendImmersiveState(v) {
     postToFrame(v, {
       type: 'moebius:immersive-state',
-      // Either flavor of hidden bar counts as "hidden" for the app helper.
-      value: v === liveVersionRef.current ? (immersive || barCollapsed) : false,
+      value: v === liveVersionRef.current && immersiveMode != null,
     })
   }
 
@@ -1151,7 +1150,7 @@ const AppCanvas = forwardRef(function AppCanvas({
       if (loadedDocsRef.current.has(v)) sendInsets(v)
     }
   // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [immersive, swap.liveVersion])
+  }, [immersiveMode, swap.liveVersion])
 
   // Keep the app's window.mobius.immersive helper in sync with the shell's
   // applied verdict (see sendImmersiveState). Same triggers as the insets echo.
@@ -1160,7 +1159,7 @@ const AppCanvas = forwardRef(function AppCanvas({
       if (loadedDocsRef.current.has(v)) sendImmersiveState(v)
     }
   // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [immersive, barCollapsed, swap.liveVersion])
+  }, [immersiveMode, swap.liveVersion])
 
   // Re-forward insets on viewport geometry change WHILE immersive. Rotating the
   // device or a window resize moves the notch/home-indicator (landscape puts
@@ -1171,7 +1170,7 @@ const AppCanvas = forwardRef(function AppCanvas({
   // listener is only attached while immersive (and torn down on exit). The
   // probe element resolves the fresh env() values after layout settles.
   useEffect(() => {
-    if (!immersive) return
+    if (immersiveMode !== 'full') return
     function onGeometryChange() { sendInsets(liveVersionRef.current) }
     window.addEventListener('resize', onGeometryChange)
     window.addEventListener('orientationchange', onGeometryChange)
@@ -1180,7 +1179,7 @@ const AppCanvas = forwardRef(function AppCanvas({
       window.removeEventListener('orientationchange', onGeometryChange)
     }
   // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [immersive])
+  }, [immersiveMode])
 
   if (!appId) {
     return (

frontend/src/components/Shell/Shell.jsx

@@ -318,8 +318,8 @@ export default function Shell() {
     '--desktop-sidebar-width': `${desktopSidebarWidth}px`,
     '--shell-tabstrip-height': `${paneModel.STRIP_H}px`,
   }), [desktopSidebarWidth])
-  // Immersive mode (moebius:immersive, .pm/128). The state is the id of the app
-  // holding an immersive request (or null); it's APPLIED — bar hidden, canvas
+  // Immersive mode (moebius:immersive, .pm/128). One state value owns the app
+  // id and requested mode; it's APPLIED — bar hidden, canvas
   // full-viewport — only while that app is the active canvas of the FOCUSED
   // pane, so switching to chat/settings/another app restores chrome
   // automatically and switching back re-enters without a re-post. The request
@@ -328,13 +328,9 @@ export default function Shell() {
   // lives there. Declared here (before the content-visibility derivation) so
   // immersive can solo its pane over the whole workspace (§4/§9). Full contract:
   // lib/immersive.js.
-  const [immersiveAppId, dispatchImmersive] = useReducer(immersiveReducer, null)
-  // Which flavor of hidden-bar the current holder asked for: 'full' (games —
-  // full-bleed under the notch) or 'bar' (general apps — hide the toolbar but
-  // keep the status-bar strip, so the app looks like a standalone PWA). Only a
-  // real-time request carries a mode; a lifecycle replay (in-place app update)
-  // omits it and leaves the last mode intact.
-  const [immersiveMode, setImmersiveMode] = useState('full')
+  const [immersiveRequest, dispatchImmersive] = useReducer(immersiveReducer, null)
+  const immersiveAppId = immersiveRequest?.appId ?? null
+  const immersiveMode = immersiveRequest?.mode ?? 'full'
   const [nowPlaying, setNowPlaying] = useState(null)
   const mediaSessionOwnerRef = useRef(null)
   if (!mediaSessionOwnerRef.current) {
@@ -348,8 +344,7 @@ export default function Shell() {
   }, [])
   // Stable identity — AppCanvas's message-listener effect depends on it.
   const handleImmersive = useCallback((appId, value, mode) => {
-    dispatchImmersive({ type: 'request', appId, value })
-    if (value && (mode === 'bar' || mode === 'full')) setImmersiveMode(mode)
+    dispatchImmersive({ type: 'request', appId, value, mode })
   }, [])
   // Immersive is a temporary overlay lease, independent of the durable builder /
   // single worlds. A verified request from the focused app may therefore solo
@@ -358,7 +353,7 @@ export default function Shell() {
   // Settings keeps its builder invariant because isImmersiveActive additionally
   // requires the active shell view to be the requesting canvas, and AppCanvas
   // forwards live requests only from its focused active frame.
-  const immersiveActive = isImmersiveActive(immersiveAppId, activeView, activeAppId)
+  const immersiveActive = isImmersiveActive(immersiveRequest, activeView, activeAppId)
   useLayoutEffect(() => {
     if (!immersiveActive) return
     const drawer = document.getElementById('navigation-drawer')
@@ -3365,8 +3360,9 @@ export default function Shell() {
               offlineCapable={!!app?.offline_capable}
               capabilityContract={app?.capability_contract || null}
               pendingIntent={appIntents[String(id)] || null}
-              immersive={immersiveActive && immersiveMode === 'full' && String(immersiveAppId) === String(id)}
-              barCollapsed={immersiveActive && immersiveMode === 'bar' && String(immersiveAppId) === String(id)}
+              immersiveMode={immersiveActive && String(immersiveAppId) === String(id)
+                ? immersiveMode
+                : null}
               onNavPush={appNavPush}
               onNavPop={appNavPop}
               onNavReset={appNavReset}

frontend/src/lib/__tests__/immersive.test.js

@@ -8,48 +8,66 @@ import {
 } from '../immersive.js'
 
 test('request value:true grants the immersive slot to the app', () => {
-  assert.equal(immersiveReducer(null, { type: 'request', appId: 7, value: true }), 7)
+  assert.deepEqual(
+    immersiveReducer(null, { type: 'request', appId: 7, value: true }),
+    { appId: 7, mode: 'full' },
+  )
 })
 
 test('request value:false from the holder releases the slot', () => {
-  assert.equal(immersiveReducer(7, { type: 'request', appId: 7, value: false }), null)
+  assert.equal(immersiveReducer(
+    { appId: 7, mode: 'full' },
+    { type: 'request', appId: 7, value: false },
+  ), null)
 })
 
 test('request value:false from a non-holder leaves the slot alone', () => {
   // A hidden cached iframe being evicted (or posting its own cleanup)
   // must not strip another app's immersive request.
-  assert.equal(immersiveReducer(7, { type: 'request', appId: 3, value: false }), 7)
+  const request = { appId: 7, mode: 'bar' }
+  assert.equal(
+    immersiveReducer(request, { type: 'request', appId: 3, value: false }),
+    request,
+  )
 })
 
-test('a later request from another app wins the slot', () => {
-  assert.equal(immersiveReducer(7, { type: 'request', appId: 3, value: true }), 3)
+test('a later request replaces owner and mode atomically', () => {
+  assert.deepEqual(immersiveReducer(
+    { appId: 7, mode: 'full' },
+    { type: 'request', appId: 3, value: true, mode: 'bar' },
+  ), { appId: 3, mode: 'bar' })
 })
 
 test('release tolerates numeric/string id mismatch', () => {
   // Shell passes numeric ids from /api/apps; some paths stringify.
-  assert.equal(immersiveReducer(7, { type: 'request', appId: '7', value: false }), null)
+  assert.equal(immersiveReducer(
+    { appId: 7, mode: 'full' },
+    { type: 'request', appId: '7', value: false },
+  ), null)
 })
 
 test('exit (the shell button) always clears, whoever holds it', () => {
-  assert.equal(immersiveReducer(7, { type: 'exit' }), null)
+  assert.equal(immersiveReducer({ appId: 7, mode: 'bar' }, { type: 'exit' }), null)
   assert.equal(immersiveReducer(null, { type: 'exit' }), null)
 })
 
 test('unknown actions are a no-op', () => {
-  assert.equal(immersiveReducer(7, { type: 'bogus' }), 7)
+  const request = { appId: 7, mode: 'full' }
+  assert.equal(immersiveReducer(request, { type: 'bogus' }), request)
 })
 
 test('immersive applies only on the canvas view with the holder active', () => {
-  assert.equal(isImmersiveActive(7, 'canvas', 7), true)
+  const request = { appId: 7, mode: 'full' }
+  assert.equal(isImmersiveActive(request, 'canvas', 7), true)
   // Same request, but the user is looking elsewhere — chrome stays.
-  assert.equal(isImmersiveActive(7, 'chat', null), false)
-  assert.equal(isImmersiveActive(7, 'settings', null), false)
+  assert.equal(isImmersiveActive(request, 'chat', null), false)
+  assert.equal(isImmersiveActive(request, 'settings', null), false)
   // Another app is active — the holder's request is dormant, not applied.
-  assert.equal(isImmersiveActive(7, 'canvas', 3), false)
+  assert.equal(isImmersiveActive(request, 'canvas', 3), false)
 })
 
 test('immersive application tolerates numeric/string id mismatch', () => {
-  assert.equal(isImmersiveActive('7', 'canvas', 7), true)
+  assert.equal(isImmersiveActive({ appId: '7', mode: 'full' }, 'canvas', 7), true)
 })
 
 test('no holder means no immersive regardless of view', () => {

frontend/src/lib/__tests__/immersiveRuntime.test.js

@@ -44,7 +44,11 @@ test('holdToToggle is idempotent and cleanup restores the target', () => {
   })
 
   cleanup()
-  assert.equal(element.__mobiusHold, undefined)
   assert.deepEqual(element.style, before)
   for (const listeners of element.listeners.values()) assert.equal(listeners.length, 0)
+
+  const rewired = immersive.holdToToggle(element)
+  assert.notEqual(rewired, cleanup)
+  assert.equal(element.listeners.get('pointerdown').length, 1)
+  rewired()
 })

frontend/src/lib/immersive.js

@@ -9,10 +9,11 @@
 // that VERIFIED event.source === its own iframe's contentWindow — never from
 // the message payload — so a frame can only toggle immersive for itself.
 //
-// The state is the id of the app that currently HOLDS an immersive request,
-// or null. Holding a request is not the same as immersive being APPLIED:
-// application additionally requires that app to be the active canvas (see
-// isImmersiveActive).
+// The state is the app's complete request ({ appId, mode }) or null. Keeping
+// ownership and presentation together prevents a mode from leaking from a
+// previous holder. Holding a request is not the same as immersive being
+// APPLIED: application additionally requires that app to be the active canvas
+// (see isImmersiveActive).
 //
 // Immersive intent is deliberately SESSIONAL, not sticky navigation state.
 // Leaving an app releases its request, and returning does not resurrect a
@@ -22,7 +23,7 @@
 // over merely because its cached iframe stayed mounted. A live frame promotion
 // is the one replay boundary; AppCanvas owns that distinction below.
 
-export function immersiveReducer(immersiveAppId, action) {
+export function immersiveReducer(request, action) {
   switch (action.type) {
     case 'request':
       // value:true grants the requesting app the immersive slot (last
@@ -32,26 +33,34 @@ export function immersiveReducer(immersiveAppId, action) {
       // cleanup-post and on iframe teardown (unmount / eviction / version
       // remount), so "app switch or unmount always restores" holds even
       // though tearing down an iframe never runs the app's own effects.
-      if (action.value) return action.appId
-      return sameApp(immersiveAppId, action.appId) ? null : immersiveAppId
+      if (action.value) {
+        const next = {
+          appId: action.appId,
+          mode: action.mode === 'bar' ? 'bar' : 'full',
+        }
+        return sameApp(request?.appId, next.appId) && request.mode === next.mode
+          ? request
+          : next
+      }
+      return sameApp(request?.appId, action.appId) ? null : request
     case 'exit':
       // The shell's floating exit button — the user always wins. The app
       // is NOT consulted; it only re-enters immersive by posting again
       // (which a mounted app won't do until it remounts).
       return null
     default:
-      return immersiveAppId
+      return request
   }
 }
 
 // Immersive is applied only while the requesting app is what the user is
 // actually looking at. Everything else — chat, settings, another app —
 // keeps normal chrome, which is what makes app-switch restoration
 // automatic: no event needs to fire, the condition just stops holding.
-export function isImmersiveActive(immersiveAppId, activeView, activeAppId) {
-  return immersiveAppId != null
+export function isImmersiveActive(request, activeView, activeAppId) {
+  return request?.appId != null
     && activeView === 'canvas'
-    && sameApp(immersiveAppId, activeAppId)
+    && sameApp(request.appId, activeAppId)
 }
 
 /**