docs: add sequence diagram to article

Author: CAMOBAP

docs/article.md

@@ -8,15 +8,21 @@ The response was... well, let's just say the React community wasn't exactly burs
 
 And that was it. Case closed. The post quietly disappeared into the digital abyss where brave but unpopular ideas go to die... or not!
 
-![Hold my beer meme](./images/hold-my-beer.png)
+<div align="center">
+  <img src="./images/hold-my-beer.png" alt="Hold my beer meme" width="400" />
+</div>
+<br/>
 
 Well, sometimes the "easier way around" is actually the boring way around, and where's the engineering joy in doing things the sensible way? I'm here to tell you that there **actually is a place for this idea**, and the `react-native-sandbox` package is here to prove it.
 
 What if I told you that you *can* actually run React Native inside React Native? Not with WebViews (ew), not with some hacky iframe solution, but with actual, honest-to-goodness React Native components rendering other React Native components in isolated JavaScript contexts?
 
 Yes, this is the story of how we took the concept of "nested apps" and made it so meta that even Christopher Nolan would be envious.
 
-![Yo Dawg meme](./images/yo-dawg.png)
+<div align="center">
+  <img src="./images/yo-dawg.png" alt="Yo Dawg meme" width="400" />
+</div>
+<br/>
 
 So we put React Native in your React Native so you can render components while you render components! It's like when someone first figured out you could run a virtual machine inside a virtual machine.
 
@@ -72,12 +78,20 @@ The `jsBundleSource` property is flexible and supports multiple ways to load you
 
 You can also control security and permissions using `allowedTurboModules` to specify which native modules the sandbox can access i.e. whitelist approach
 
+Communication works between the host app and sandbox instances using Fabric Native Components:
+
+<div align="center">
+  <img src="./communication-fabric-components.png" alt="Communication Architecture between Host and Sandbox" width="600" />
+</div>
+
 ## It's show time!
 
 Our demo app is delightfully destructive—in the name of science, of course.
 
-![Demo Screenshot](../apps/demo/docs/screenshot.png)
-
+<div align="center" style="width: 240px; height: 300px; margin: 0 auto;">
+  <img src="../apps/demo/docs/screenshot.png" alt="Demo Screenshot" style="width: 100%; height: 100%; object-fit: cover; object-position: top;" />
+</div>
+<br/>
 On the left, you'll see the "Main App" column running a component directly in the host application. On the right, the "Sandboxed" column runs the exact same component inside a `SandboxReactNativeView`. While they visually look identical, the sandboxed version is running in complete isolation.
 
 ```jsx
@@ -131,5 +145,9 @@ A: Yes. You can whitelist which native modules (TurboModules) are available to e
 
 We have a lot of ideas of upcoming features in our [Roadmap](https://github.com/callstackincubator/react-native-sandbox?tab=readme-ov-file#-roadmap) is something is missing don't hesitate to [let us know](https://github.com/callstackincubator/react-native-sandbox/issues/new)
 
-[![Let's see how deep recursive example goes](./images/how-deep.png)](https://github.com/callstackincubator/react-native-sandbox/blob/main/apps/recursive/README.md)
+<div align="center">
+  <a href="https://github.com/callstackincubator/react-native-sandbox/blob/main/apps/recursive/README.md">
+    <img src="./images/how-deep.png" alt="Let's see how deep recursive example goes" width="400" />
+  </a>
+</div>
 

docs/communication-fabric-components.plantuml

@@ -0,0 +1,87 @@
+@startuml
+
+!theme aws-orange
+skinparam DefaultFontSize 16
+skinparam DefaultFontName "Inter, system-ui, sans-serif"
+
+skinparam ParticipantBackgroundColor #F8FAFC
+skinparam ParticipantBorderColor #64748B
+skinparam ParticipantFontColor #1E293B
+skinparam ParticipantFontSize 14
+skinparam ParticipantFontStyle bold
+
+skinparam ActorBackgroundColor #EFF6FF
+skinparam ActorBorderColor #3B82F6
+skinparam ActorFontColor #1E40AF
+
+skinparam GroupBorderColor #E2E8F0
+skinparam GroupBackgroundColor #F1F5F9
+skinparam GroupFontColor #475569
+skinparam GroupFontSize 13
+skinparam GroupFontStyle bold
+
+skinparam NoteBackgroundColor #F3F4F6
+skinparam NoteBorderColor #C4B5FD
+skinparam NoteFontColor #5B21B6
+skinparam NoteFontSize 12
+
+skinparam ArrowColor #64748B
+skinparam ArrowFontColor #374151
+skinparam ArrowFontSize 12
+
+skinparam SequenceMessageAlign center
+
+participant HostReactInstance
+participant SandboxReactNativeView
+participant SandboxReactInstance
+participant "//SandboxReactNativeDelegate//" as Delegate
+
+note over SandboxReactInstance
+  **Isolated JavaScript VM**
+  Separate JSI runtime with
+  own global scope and context
+end note
+
+group Initialize Sandbox
+
+HostReactInstance -> SandboxReactNativeView : <SandboxReactNativeView>\n  onMessage={handleMessage}\n  onError={handleError}\n/>
+SandboxReactNativeView -> Delegate : create delegate with configuration
+SandboxReactNativeView -> SandboxReactInstance : create isolated React instance\n(via RCTReactNativeFactory)
+Delegate -> SandboxReactInstance : setup runtime & inject globals
+note right of SandboxReactInstance
+  Manages and configures the
+  isolated React instance, injects
+  global ""postMessage"" and ""setOnMessage""
+  functions into sandbox runtime
+end note
+
+end
+
+...
+
+group Host -> Sandbox
+
+HostReactInstance -> SandboxReactNativeView : postMessage(JSON.stringify({\naction: "SETUP_SND",\ndata: { unit: 'm', ...}\n}))
+SandboxReactNativeView -> SandboxReactInstance: call onMessage handler\n(via injected globals)
+
+end
+
+...
+
+group Sandbox -> Host
+
+SandboxReactInstance -> SandboxReactNativeView : global.postMessage({action: "ADD_MENU_ITEM"})
+SandboxReactNativeView -> HostReactInstance: onMessage callback\n(via Fabric Event Emitter)
+
+end
+
+...
+
+group Error Handling
+
+SandboxReactInstance -> SandboxReactNativeView : JavaScript error occurs
+SandboxReactNativeView -> HostReactInstance: onError callback\n(via Fabric Event Emitter)
+
+end
+
+@enduml

docs/communication-fabric-components.png

@@ -2,59 +2,59 @@
 
 skinparam DefaultFontSize 21
 
-participant AppReactInstance
-participant MultiReactMediatorModule1
+participant HostReactInstance
+participant SandboxReactNativeView
 
-participant "//ReactInstanceRegistry//" as ReactInstanceRegistry
+participant "//SandboxReactNativeDelegate//" as Delegate
 
-participant MultiReactMediatorModule2
 participant SandboxReactInstance
 
-note over ReactInstanceRegistry
-  It's not actual class or struct
-  but rather a ""std::map"". To
-  thread-safe access to registered
-  ""jsi::Runtime"" by ""std::string""
-  symbolic name
+note over Delegate
+  Creates isolated React instance,
+  injects global ""postMessage"" and
+  ""setOnMessage"" functions into
+  sandbox JavaScript runtime
 end note
 
-group Register App
+group Initialize Sandbox
 
-AppReactInstance -> MultiReactMediatorModule1 : registerRuntime("App", onSandboxMessage)
-MultiReactMediatorModule1 -> ReactInstanceRegistry : store pointer to jsi::Runtime
+HostReactInstance -> SandboxReactNativeView : <SandboxReactNativeView>\n  onMessage={handleMessage}\n  onError={handleError}\n/>
+SandboxReactNativeView -> Delegate : create isolated React instance
+Delegate -> SandboxReactInstance : setup runtime & inject globals
+note right of SandboxReactInstance
+  ""global.postMessage"" - send to host
+  ""global.setOnMessage"" - listen from host
+end note
 
 end
 
 ...
 
-group App start Sandbox
-
-SandboxReactInstance -> MultiReactMediatorModule2 : registerRuntime("Sandbox", onAppMessage)
-MultiReactMediatorModule2 -> ReactInstanceRegistry : store pointer to jsi::Runtime
+group Host -> Sandbox
 
-AppReactInstance -> MultiReactMediatorModule1 : postMessage(\n  "Sandbox",\n  {\n    action: "SETUP",\n    data: { language: 'PL', units: 'm' ...}\n  }\n)
-MultiReactMediatorModule1 -> ReactInstanceRegistry : get pointer to jsi::Runtime
-MultiReactMediatorModule1 -> SandboxReactInstance: onAppMessage (via ""jsi::Runtime"")
+HostReactInstance -> SandboxReactNativeView : Commands.postMessage(\n  JSON.stringify({\n    action: "SETUP",\n    data: { language: 'PL', units: 'm' ...}\n  })\n)
+SandboxReactNativeView -> Delegate : postMessage(message)
+Delegate -> SandboxReactInstance: call onMessage handler\n(via ""jsi::Runtime"")
 
 end
 
 ...
 
-group Sandbox -> App
+group Sandbox -> Host
 
-SandboxReactInstance -> MultiReactMediatorModule2 : postMessage(\n  "App",\n  {action: "ADD_MENU_ITEM"}\n)
-MultiReactMediatorModule2 -> ReactInstanceRegistry : get pointer to jsi::Runtime
-MultiReactMediatorModule2 -> AppReactInstance: onSandboxMessage (via ""jsi::Runtime"")
+SandboxReactInstance -> Delegate : global.postMessage(\n  {action: "ADD_MENU_ITEM"}\n)
+Delegate -> SandboxReactNativeView: emit onMessage event\n(via Fabric Event Emitter)
+SandboxReactNativeView -> HostReactInstance: onMessage callback\nwith event data
 
 end
 
 ...
 
-group App -> Sandbox
+group Error Handling
 
-AppReactInstance -> MultiReactMediatorModule1 : postMessage(\n  "Sandbox",\n    {action: "UPDATE_PROFILE"}\n)
-MultiReactMediatorModule1 -> ReactInstanceRegistry : get pointer to jsi::Runtime
-MultiReactMediatorModule1 -> SandboxReactInstance: onAppMessage (via ""jsi::Runtime"")
+SandboxReactInstance -> Delegate : JavaScript error occurs
+Delegate -> SandboxReactNativeView: emit onError event\n(via Fabric Event Emitter)
+SandboxReactNativeView -> HostReactInstance: onError callback\nwith error details
 
 end