feat(remote-control): add Pusher sync so desktop shows overlay and refreshes iframe when mobile edits

- Server triggers remote-control-start/complete events on sandbox-${sandboxId} channel
- Desktop chat panel shows full-cover overlay while mobile agent is editing
- iFrame remounts on complete to guarantee latest preview is shown
- Mobile ChatScreen sends source: 'remote-control' to identify requests

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: bidah

apps/web/app/(app)/api/chat/route.ts

@@ -5,6 +5,7 @@ import { canUserSendMessage, incrementMessageUsage } from '@/lib/message-usage'
 import { corsHeaders, handleCorsOptions } from '@/lib/cors'
 import { dispatchToAgent } from '@/lib/agent-dispatcher'
 import type { AgentType } from '@/lib/agent-dispatcher'
+import { getPusherServer } from '@react-native-vibe-code/pusher/server'
 
 type ClaudeCodeResponse = {
   type: 'message' | 'completion' | 'error'
@@ -30,6 +31,7 @@ export async function POST(req: Request) {
     imageAttachments,
     skills,
     agentType,
+    source,
   }: {
     messages: UIMessage[]
     projectId: string
@@ -40,18 +42,23 @@ export async function POST(req: Request) {
     imageAttachments?: Array<{ url: string; contentType: string; name: string; size: number }>
     skills?: string[]
     agentType?: AgentType
+    source?: string
   } = await req.json()
 
+  const isRemoteControl = source === 'remote-control'
+
   // If userId not provided (mobile app), look it up from the project
   let userId = bodyUserId
-  if (!userId && projectId) {
+  let remoteSandboxId: string | null = null
+  if ((!userId || isRemoteControl) && projectId) {
     const project = await db
-      .select({ userId: projects.userId })
+      .select({ userId: projects.userId, sandboxId: projects.sandboxId })
       .from(projects)
       .where(eq(projects.id, projectId))
       .limit(1)
     if (project.length > 0) {
-      userId = project[0].userId
+      if (!userId) userId = project[0].userId
+      remoteSandboxId = project[0].sandboxId ?? null
     }
   }
 
@@ -368,6 +375,20 @@ export async function POST(req: Request) {
                     }
                   }, 10000) // Check every 10 seconds
 
+                  // Notify desktop that remote control is editing
+                  if (isRemoteControl && remoteSandboxId) {
+                    try {
+                      const pusher = getPusherServer()
+                      await pusher.trigger(
+                        `sandbox-${remoteSandboxId}`,
+                        'remote-control-start',
+                        {}
+                      )
+                    } catch (e) {
+                      console.error('[Chat Route] Failed to trigger remote-control-start:', e)
+                    }
+                  }
+
                   try {
                     // Call the handler module directly - no HTTP, no timeout issues!
                     await dispatchToAgent(
@@ -416,6 +437,20 @@ export async function POST(req: Request) {
                           // Save to DB BEFORE closing the stream
                           await saveMessagesToDatabase(fullContent, 'onComplete')
 
+                          // Notify desktop that remote control is done
+                          if (isRemoteControl && remoteSandboxId) {
+                            try {
+                              const pusher = getPusherServer()
+                              await pusher.trigger(
+                                `sandbox-${remoteSandboxId}`,
+                                'remote-control-complete',
+                                {}
+                              )
+                            } catch (e) {
+                              console.error('[Chat Route] Failed to trigger remote-control-complete:', e)
+                            }
+                          }
+
                           // Use safe helpers for final message and close
                           safeEnqueue({
                             type: 'text-delta',
@@ -435,6 +470,20 @@ export async function POST(req: Request) {
                           // Save to DB BEFORE closing the stream
                           await saveMessagesToDatabase(fullContent, 'onError')
 
+                          // Notify desktop that remote control is done (even on error)
+                          if (isRemoteControl && remoteSandboxId) {
+                            try {
+                              const pusher = getPusherServer()
+                              await pusher.trigger(
+                                `sandbox-${remoteSandboxId}`,
+                                'remote-control-complete',
+                                {}
+                              )
+                            } catch (e) {
+                              console.error('[Chat Route] Failed to trigger remote-control-complete on error:', e)
+                            }
+                          }
+
                           safeCloseStream('error', errorContent)
                         },
                       }

apps/web/app/(app)/p/[id]/project-page.tsx

@@ -2472,6 +2472,7 @@ export function ProjectPageInternal({ opencodeEnabled = false, template: templat
                   isCloudPanelOpen={mobileSidebarPanel === 'cloud'}
                   onCloudPanelOpen={() => setMobileSidebarPanel('cloud')}
                   onCloudPanelClose={() => setMobileSidebarPanel(null)}
+                  onIframeRefresh={() => setPreviewKey(prev => prev + 1)}
                 />
                 {latestError && (
                   <ErrorNotificationCard
@@ -2582,6 +2583,7 @@ export function ProjectPageInternal({ opencodeEnabled = false, template: templat
                   isCloudPanelOpen={desktopSidebarPanel === 'cloud'}
                   onCloudPanelOpen={() => setDesktopSidebarPanel('cloud')}
                   onCloudPanelClose={() => setDesktopSidebarPanel(null)}
+                  onIframeRefresh={() => setPreviewKey(prev => prev + 1)}
                 />
                 {latestError && (
                   <ErrorNotificationCard

apps/web/components/chat-panel.tsx

@@ -6,6 +6,7 @@ import { Messages } from '@/components/chat/messages'
 import type { Message } from 'ai'
 import type React from 'react'
 import { usePusherHoverSelection } from '@/hooks/usePusherHoverSelection'
+import { useRemoteControlStatus } from '@/hooks/useRemoteControlStatus'
 
 interface ChatPanelProps {
   messages: Message[]
@@ -37,6 +38,7 @@ interface ChatPanelProps {
   isCloudPanelOpen?: boolean
   onCloudPanelOpen?: () => void
   onCloudPanelClose?: () => void
+  onIframeRefresh?: () => void
 }
 
 export function ChatPanel({
@@ -62,9 +64,16 @@ export function ChatPanel({
   isCloudPanelOpen = false,
   onCloudPanelOpen,
   onCloudPanelClose,
+  onIframeRefresh,
 }: ChatPanelProps) {
+  const { isRemoteControlActive } = useRemoteControlStatus({
+    sandboxId: sandboxId ?? null,
+    onComplete: onIframeRefresh,
+  })
+
   return (
     <BaseChatPanel
+      isRemoteControlActive={isRemoteControlActive}
       messages={messages}
       input={input}
       handleInputChange={handleInputChange}

apps/web/hooks/useRemoteControlStatus.ts

@@ -0,0 +1,46 @@
+'use client'
+
+import PusherClient from 'pusher-js'
+import { useEffect, useState, useRef } from 'react'
+
+export function useRemoteControlStatus({
+  sandboxId,
+  onComplete,
+}: {
+  sandboxId: string | null
+  onComplete?: () => void
+}) {
+  const [isRemoteControlActive, setIsRemoteControlActive] = useState(false)
+  const pusherRef = useRef<PusherClient | null>(null)
+  const onCompleteRef = useRef(onComplete)
+  onCompleteRef.current = onComplete
+
+  useEffect(() => {
+    if (!sandboxId) return
+
+    const pusher = new PusherClient(process.env.NEXT_PUBLIC_PUSHER_APP_KEY!, {
+      cluster: process.env.NEXT_PUBLIC_PUSHER_CLUSTER!,
+    })
+    pusherRef.current = pusher
+
+    const channel = pusher.subscribe(`sandbox-${sandboxId}`)
+
+    channel.bind('remote-control-start', () => {
+      setIsRemoteControlActive(true)
+    })
+
+    channel.bind('remote-control-complete', () => {
+      setIsRemoteControlActive(false)
+      onCompleteRef.current?.()
+    })
+
+    return () => {
+      channel.unbind_all()
+      channel.unsubscribe()
+      pusher.disconnect()
+      pusherRef.current = null
+    }
+  }, [sandboxId])
+
+  return { isRemoteControlActive }
+}

docs/plans/2026-03-09-remote-control-pusher-design.md

@@ -0,0 +1,49 @@
+# Remote Control Pusher Integration Design
+
+## Overview
+
+When a mobile user triggers a chat via the Remote Control package, the desktop web chat panel should show a blocking overlay ("Remote Control is editing the app"), then refresh the iframe preview once the agent completes.
+
+## Pusher Events
+
+Add to `packages/visual-edits/src/types/index.ts` on the existing `sandbox-${sandboxId}` channel:
+
+- `remote-control-start` — fired when server begins processing a mobile chat request
+- `remote-control-complete` — fired when server finishes streaming the response
+
+## Server Changes
+
+The chat API route (`apps/web/app/api/chat/route.ts`) detects mobile requests via `source: 'remote-control'` in the request body. At stream start it triggers `remote-control-start`; at stream end it triggers `remote-control-complete`.
+
+## Web Hook
+
+New `useRemoteControlStatus(sandboxId, onComplete)` hook in `packages/visual-edits/src/web/`:
+
+- Subscribes to `sandbox-${sandboxId}` channel
+- `remote-control-start` → `isRemoteControlActive = true`
+- `remote-control-complete` → `isRemoteControlActive = false`, calls `onComplete`
+- `onComplete` increments `iframeKey` in `preview-panel.tsx` to remount the iframe
+
+## Overlay Component
+
+New `RemoteControlOverlay` in `packages/chat/src/components/`:
+
+- Full-cover absolute overlay on the chat panel
+- Shows spinner + "Remote Control is editing the app"
+- No dismiss — only server clears it
+- `BaseChatPanel` gets new optional prop `isRemoteControlActive?: boolean`
+
+## Data Flow
+
+```
+Mobile chat request (source: 'remote-control')
+  → server triggers remote-control-start
+  → desktop overlay shown, chat blocked
+  → server finishes streaming
+  → server triggers remote-control-complete
+  → overlay removed, iframeKey++ → iframe remounts
+```
+
+## Mobile Changes
+
+`ChatScreen.tsx` sends `source: 'remote-control'` in the chat request body. No other mobile changes needed.

packages/chat/src/components/chat-panel.tsx

@@ -53,6 +53,8 @@ export interface ChatPanelProps {
   isCloudPanelOpen?: boolean
   onCloudPanelOpen?: () => void
   onCloudPanelClose?: () => void
+  /** Whether remote control (mobile) is currently editing */
+  isRemoteControlActive?: boolean
   /** Render function for messages container */
   renderMessages: (props: {
     messages: Message[]
@@ -119,6 +121,7 @@ export function ChatPanel({
   isCloudPanelOpen = false,
   onCloudPanelOpen,
   onCloudPanelClose,
+  isRemoteControlActive = false,
   renderMessages,
   renderInput,
   useHoverSelection,
@@ -191,6 +194,14 @@ export function ChatPanel({
   return (
     <div className="flex flex-col border-r relative overflow-hidden h-full flex-1 min-h-0">
 
+      {/* Remote Control overlay */}
+      {isRemoteControlActive && (
+        <div className="absolute inset-0 z-50 flex flex-col items-center justify-center bg-background/95 backdrop-blur-sm">
+          <div className="h-8 w-8 animate-spin rounded-full border-2 border-foreground border-t-transparent mb-4" />
+          <p className="text-sm font-medium text-foreground">Remote Control is editing the app</p>
+        </div>
+      )}
+
       {/* Messages Container with Conversation (use-stick-to-bottom) */}
       {renderMessages({
         messages,

packages/remote-control/src/ChatScreen.tsx

@@ -182,6 +182,7 @@ export function ChatScreen({ onNavigateHome, onClose, selectedProject }: ChatScr
       const newBody = {
         projectId: requestData?.body?.projectId || selectedProject?.id || projectId,
         messages: lastUserMessage ? [lastUserMessage] : [],
+        source: 'remote-control',
       }
 
       console.log('[ChatScreen] Final request body:', newBody)

packages/visual-edits/src/types/index.ts

@@ -162,6 +162,10 @@ export const PUSHER_EVENTS = {
   HOVER_MODE_TOGGLE: 'hover-mode-toggle',
   /** Event when element is selected in sandbox */
   HOVER_SELECTION: 'hover-selection',
+  /** Event when remote control (mobile) starts editing */
+  REMOTE_CONTROL_START: 'remote-control-start',
+  /** Event when remote control (mobile) finishes editing */
+  REMOTE_CONTROL_COMPLETE: 'remote-control-complete',
 } as const
 
 /**

packages/visual-edits/src/web/index.ts

@@ -12,6 +12,8 @@ export { SelectionIndicator, getFileEditionRef } from './SelectionIndicator'
 export type { SelectionIndicatorExtendedProps } from './SelectionIndicator'
 
 export { usePusherHoverSelection } from './usePusherHoverSelection'
+export { useRemoteControlStatus } from './useRemoteControlStatus'
+export type { UseRemoteControlStatusOptions, UseRemoteControlStatusResult } from './useRemoteControlStatus'
 
 // Re-export types for convenience
 export type {

packages/visual-edits/src/web/useRemoteControlStatus.ts

@@ -0,0 +1,53 @@
+'use client'
+
+import PusherClient from 'pusher-js'
+import { useEffect, useState, useRef, useCallback } from 'react'
+import { PUSHER_EVENTS, getSandboxChannelName } from '../types'
+
+export interface UseRemoteControlStatusOptions {
+  sandboxId: string | null
+  onComplete?: () => void
+}
+
+export interface UseRemoteControlStatusResult {
+  isRemoteControlActive: boolean
+}
+
+export function useRemoteControlStatus({
+  sandboxId,
+  onComplete,
+}: UseRemoteControlStatusOptions): UseRemoteControlStatusResult {
+  const [isRemoteControlActive, setIsRemoteControlActive] = useState(false)
+  const pusherRef = useRef<PusherClient | null>(null)
+  const onCompleteRef = useRef(onComplete)
+  onCompleteRef.current = onComplete
+
+  useEffect(() => {
+    if (!sandboxId) return
+
+    const pusher = new PusherClient(process.env.NEXT_PUBLIC_PUSHER_APP_KEY!, {
+      cluster: process.env.NEXT_PUBLIC_PUSHER_CLUSTER!,
+    })
+    pusherRef.current = pusher
+
+    const channel = pusher.subscribe(getSandboxChannelName(sandboxId))
+
+    channel.bind(PUSHER_EVENTS.REMOTE_CONTROL_START, () => {
+      setIsRemoteControlActive(true)
+    })
+
+    channel.bind(PUSHER_EVENTS.REMOTE_CONTROL_COMPLETE, () => {
+      setIsRemoteControlActive(false)
+      onCompleteRef.current?.()
+    })
+
+    return () => {
+      channel.unbind_all()
+      channel.unsubscribe()
+      pusher.disconnect()
+      pusherRef.current = null
+    }
+  }, [sandboxId])
+
+  return { isRemoteControlActive }
+}