# tlabaltoh/tlabwebview architecture

> Architecture diagram of the GitHub repository tlabaltoh/tlabwebview, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tlabaltoh/tlabwebview
- Repository: https://github.com/tlabaltoh/tlabwebview

## Overview

1. **What this repo is**
   - `TLabWebView` is a Unity package that embeds an Android browser component (`WebView` or `GeckoView`) into Unity UI by rendering the page into a texture and presenting it as uGUI.
   - The package is split into a **managed Unity/C# layer** and an **Android native plugin layer**.

2. **Top-level architectural boundary**
   - The main boundary is **Unity runtime code** in `Runtime/` versus **Android native code** packaged as `Plugins/Android/libTLabWebView-release.aar`.
   - C# code orchestrates browser instances, input, UI widgets, and capture strategy; the Android plugin owns the actual browser engine and platform-specific rendering.

3. **Core runtime coordination**
   - `BrowserManager` is the scene-level entry point; the README says it should be added to a GameObject and it coordinates browser lifecycle for the scene.
   - `BrowserContainer` appears to be the per-instance holder that binds a browser engine, rendering mode, and Unity-facing object graph.
   - `Browser`, `WebView`, and `GeckoView` define the main browser abstraction and engine-specific implementations.

4. **Browser abstraction and instance model**
   - `IBrowser` is the key interface boundary for browser engines.
   - `Browser`/`WebView`/`GeckoView` are likely the managed façade over the Android component, while `BrowserContainer` and `BrowserManager` handle instance creation, reuse, and concurrent browsers.
   - The README explicitly supports **multiple browser instances running concurrently**.

5. **Rendering pipeline**
   - This plugin’s main function is to convert browser output into a Unity-consumable surface/texture.
   - `IOffscreen` and `FragmentCapture` indicate the offscreen capture path from Android rendering into Unity.
   - The README lists three capture/rendering methods that materially shape the architecture:
     - **HardwareBuffer**: Android low-level, highest performance
     - **ByteBuffer**: C# receives frames as byte arrays, default/stable path
     - **Surface**: direct rendering to Android `Surface`, useful for layered composition use cases

6. **Native plugin responsibilities**
   - `NativePlugin` is the C# bridge to the Android `.aar`.
   - The native side is where browser creation, page loading, frame capture, and platform-specific browser interactions happen.
   - `Plugins/Android/copy.bat` and the packaged AAR indicate the plugin is distributed as a prebuilt Android binary, not source in this repo.

7. **Input and interaction flow**
   - Input flows from Unity UI/EventSystem into browser input adapters: `BaseInputListener`, `BrowserInputListener`, and `BrowserInputField`.
   - This layer handles keyboard focus, touch interaction, and text entry mapping between Unity and the browser component.
   - The README emphasizes support for keyboard input and touch interaction, which are central to the runtime behavior.

8. **UI overlay widgets**
   - The `Runtime/Widget/` subsystem provides Unity-side replacements for browser UI that Android browser engines don’t expose well or don’t support consistently.
   - Widgets include `AlertDialog`, `AuthWidget`, `ColorWidget`, `DateTimeWidget`, `NumberPicker`, `SelectWidget`, and `TextWidget`.
   - This forms a second UI boundary: browser page events can trigger native-style Unity widgets instead of relying only on browser-internal dialogs/forms.

9. **Message passing and JS integration**
   - `Runtime/Common.cs` and sample scripts suggest a JS-to-C# bridge.
   - For `WebView`, the README mentions `window.tlab` as the browser-side JavaScript interface.
   - For `GeckoView`, that interface is not fully supported yet; pages send messages through `window.postMessage` with a special payload format instead. This is an important engine-specific integration boundary.

10. **Sample and test subsystems**
    - `Runtime/Sample/` and `Runtime/Test/` are not core architecture, but they document and validate the plugin’s behavior.
    - Samples cover browser usage, background rendering, download handling, focus interactions, local file loading, JS snippets, and widget scenarios.
    - Tests such as `BrowserAPITest`, `LoadUnloadTest`, and `OnMessageTest` indicate the main integration seams: lifecycle, message routing, and cleanup.

11. **Packaging and editor-time build integration**
    - `Runtime/TLab.WebView.Runtime.asmdef` and `Editor/TLab.WebView.Editor.asmdef` split runtime and editor concerns.
    - `Editor/Scripts/UnityWebViewPostprocessBuild.cs` is the build-time hook that likely injects Android settings, dependencies, and packaging steps.
    - `Editor/MediationAdapterDependencies.xml` suggests Android dependency management during build, not during runtime.

12. **Assets and prefab-based entry points**
    - `Resources/TLab/WebView/Browser.prefab` is the primary reusable prefab that binds the runtime pieces into a drop-in UI component.
    - Additional sample prefabs under `Resources/TLab/WebView/Samples/` show concrete compositions for browser views and widgets.
    - `Samples/Scenes/` provides example Unity scenes that demonstrate the intended object graph and scene setup.

13. **Platform and runtime constraints**
    - This is an **Android-only runtime**; the README notes it does not display pages in the Unity Editor.
    - The supported graphics/runtime conditions matter architecturally: Android 10–14, Unity 2021/2022/6000, OpenGLES or Vulkan, with some rendering modes being more stable under OpenGLES.
    - `GeckoView` requires higher Android/API and additional Gradle dependencies, making it a conditional backend rather than the default path.

14. **External dependencies and permissions**
    - The package depends on a companion keyboard package (`TLabVKeyborad`) and, for GeckoView, external Android/Gradle dependencies plus a separate GeckoView AAR.
    - Build-time flags and Android permissions control capabilities like cleartext traffic, camera/microphone access, and external storage downloads.
    - These are not just configuration details: they affect whether the browser backend can access certain web features and file operations.

15. **Overall data flow**
    - User input enters Unity UI → `BrowserManager`/`BrowserContainer` route it to the selected browser engine → Android native plugin executes browser actions and renders frames → frames are captured via the selected offscreen mode → Unity displays them as a texture in the prefab/UI.
    - Browser-to-Unity communication flows back through JS messaging and callbacks, with widget overlays handling cases where browser engine behavior is insufficient or inconsistent.

Main entry points: [`Runtime/Browser.cs`](https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/Browser.cs) (Browser), [`Runtime/BrowserContainer.cs`](https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/BrowserContainer.cs) (Browser Container), [`Runtime/NativePlugin.cs`](https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/NativePlugin.cs) (Native Plugin), [`Runtime/BrowserInputListener.cs`](https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/BrowserInputListener.cs) (Browser Input)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_browser_manager["Browser Manager<br/>scene controller<br/>[BrowserManager.cs]"]
  node_browser_container["Browser Container<br/>instance host"]
  node_browser_facade["Browser<br/>managed facade<br/>[Browser.cs]"]
  node_webview_backend["WebView<br/>browser backend<br/>[WebView.cs]"]
  node_geckoview_backend["GeckoView<br/>browser backend<br/>[GeckoView.cs]"]
  node_browser_interface["IBrowser<br/>engine contract<br/>[IBrowser.cs]"]
  node_offscreen_capture["Offscreen Capture<br/>render pipeline<br/>[IOffscreen.cs]"]
  node_fragment_capture["Fragment Capture<br/>capture path<br/>[FragmentCapture.cs]"]
  node_native_bridge["Native Plugin<br/>android bridge<br/>[NativePlugin.cs]"]
  node_input_layer["Input Layer<br/>input routing"]
  node_browser_input["Browser Input<br/>input adapter"]
  node_input_field["Input Field<br/>text bridge"]
  node_widget_system["Widgets<br/>ui overlay<br/>[Widget.cs]"]
  node_message_bridge["JS Bridge<br/>message bridge<br/>[Common.cs]"]
  node_runtime_asmdef["Runtime asmdef<br/>assembly definition"]
end

subgraph group_native["Android Plugin"]
  node_android_aar[("Android AAR<br/>native binary")]
  node_copy_script["Copy Script<br/>packaging helper<br/>[copy.bat]"]
end

subgraph group_editor["Editor"]
  node_postprocess_build["Postprocess Build<br/>build hook"]
  node_deps_xml["Deps XML<br/>android deps"]
  node_editor_asmdef["Editor asmdef<br/>assembly definition"]
end

subgraph group_samples["Samples"]
  node_browser_prefab["Browser Prefab<br/>prefab entry<br/>[Browser.prefab]"]
  node_sample_scene["Sample Scenes<br/>demo scenes"]
end

node_browser_manager -->|"creates"| node_browser_container
node_browser_container -->|"hosts"| node_browser_facade
node_browser_facade -->|"implements"| node_browser_interface
node_browser_facade -->|"webview mode"| node_webview_backend
node_browser_facade -->|"gecko mode"| node_geckoview_backend
node_browser_container -->|"captures"| node_offscreen_capture
node_offscreen_capture -->|"uses"| node_fragment_capture
node_fragment_capture -->|"drives"| node_native_bridge
node_browser_facade -->|"calls"| node_native_bridge
node_input_layer -->|"routes to"| node_browser_input
node_browser_input -->|"focuses"| node_input_field
node_browser_input -->|"targets"| node_browser_container
node_browser_container -->|"spawns"| node_widget_system
node_widget_system -->|"reports"| node_message_bridge
node_browser_facade -->|"messages"| node_message_bridge
node_message_bridge -->|"bridges"| node_native_bridge
node_postprocess_build -->|"configures"| node_deps_xml
node_postprocess_build -->|"packages"| node_android_aar
node_editor_asmdef -->|"contains"| node_postprocess_build
node_copy_script -->|"distributes"| node_android_aar
node_browser_prefab -->|"wires"| node_browser_manager
node_sample_scene -->|"demonstrates"| node_browser_prefab
node_runtime_asmdef -->|"includes"| node_browser_manager
node_android_aar -->|"backing engine"| node_native_bridge

click node_browser_manager "https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/BrowserManager.cs"
click node_browser_container "https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/BrowserContainer.cs"
click node_browser_facade "https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/Browser.cs"
click node_webview_backend "https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/WebView.cs"
click node_geckoview_backend "https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/GeckoView.cs"
click node_browser_interface "https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/IBrowser.cs"
click node_offscreen_capture "https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/IOffscreen.cs"
click node_fragment_capture "https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/FragmentCapture.cs"
click node_native_bridge "https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/NativePlugin.cs"
click node_input_layer "https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/BaseInputListener.cs"
click node_browser_input "https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/BrowserInputListener.cs"
click node_input_field "https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/BrowserInputField.cs"
click node_widget_system "https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/Widget/Widget.cs"
click node_message_bridge "https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/Common.cs"
click node_runtime_asmdef "https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/TLab.WebView.Runtime.asmdef"
click node_postprocess_build "https://github.com/tlabaltoh/tlabwebview/blob/master/Editor/Scripts/UnityWebViewPostprocessBuild.cs"
click node_deps_xml "https://github.com/tlabaltoh/tlabwebview/blob/master/Editor/MediationAdapterDependencies.xml"
click node_editor_asmdef "https://github.com/tlabaltoh/tlabwebview/blob/master/Editor/TLab.WebView.Editor.asmdef"
click node_android_aar "https://github.com/tlabaltoh/tlabwebview/blob/master/Plugins/Android/libTLabWebView-release.aar"
click node_copy_script "https://github.com/tlabaltoh/tlabwebview/blob/master/Plugins/Android/copy.bat"
click node_browser_prefab "https://github.com/tlabaltoh/tlabwebview/blob/master/Resources/TLab/WebView/Browser.prefab"
click node_sample_scene "https://github.com/tlabaltoh/tlabwebview/blob/master/Samples/Scenes/Mobile Sample.unity"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser_manager,node_browser_container,node_browser_facade,node_webview_backend,node_geckoview_backend,node_browser_interface,node_offscreen_capture,node_fragment_capture,node_native_bridge,node_input_layer,node_browser_input,node_input_field,node_widget_system,node_message_bridge,node_runtime_asmdef toneBlue
class node_android_aar,node_copy_script toneAmber
class node_postprocess_build,node_deps_xml,node_editor_asmdef toneMint
class node_browser_prefab,node_sample_scene toneRose
```

## Components

### Runtime

Unity managed browser orchestration, rendering, input, and widgets.

- [Browser Manager](https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/BrowserManager.cs): scene controller · Scene-level entry point that coordinates browser lifecycle and instance wiring. · `Runtime/BrowserManager.cs`
- [Browser Container](https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/BrowserContainer.cs): instance host · Per-browser Unity-side container that binds engine, capture mode, and presentation. · `Runtime/BrowserContainer.cs`
- [Browser](https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/Browser.cs): managed facade · High-level browser abstraction used by Unity code to drive page loading and state. · `Runtime/Browser.cs`
- [WebView](https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/WebView.cs): browser backend · Managed implementation for the Android WebView-backed browser path. · `Runtime/WebView.cs`
- [GeckoView](https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/GeckoView.cs): browser backend · Managed implementation for the GeckoView-backed browser path. · `Runtime/GeckoView.cs`
- [IBrowser](https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/IBrowser.cs): engine contract · Interface boundary for browser engines and their Unity-facing operations. · `Runtime/IBrowser.cs`
- [Offscreen Capture](https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/IOffscreen.cs): render pipeline · Abstraction for converting browser output into Unity-consumable frames. · `Runtime/IOffscreen.cs`
- [Fragment Capture](https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/FragmentCapture.cs): capture path · Unity-side capture implementation for browser rendering fragments and frame transfer. · `Runtime/FragmentCapture.cs`
- [Native Plugin](https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/NativePlugin.cs): android bridge · C# bridge to the packaged Android AAR for browser creation, loading, and capture. · `Runtime/NativePlugin.cs`
- [Input Layer](https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/BaseInputListener.cs): input routing · Base input listener layer that maps Unity events to browser interaction. · `Runtime/BaseInputListener.cs`
- [Browser Input](https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/BrowserInputListener.cs): input adapter · Browser-specific input handling for touch, focus, and keyboard interaction. · `Runtime/BrowserInputListener.cs`
- [Input Field](https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/BrowserInputField.cs): text bridge · Unity text-entry bridge for browser forms and keyboard focus behavior. · `Runtime/BrowserInputField.cs`
- [Widgets](https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/Widget/Widget.cs): ui overlay · Unity-side replacement widgets for browser dialogs and form controls. · `Runtime/Widget/Widget.cs`
- [JS Bridge](https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/Common.cs): message bridge · Shared browser-to-Unity messaging and common integration helpers. · `Runtime/Common.cs`
- [Runtime asmdef](https://github.com/tlabaltoh/tlabwebview/blob/master/Runtime/TLab.WebView.Runtime.asmdef): assembly definition · Unity assembly boundary for the runtime package. · `Runtime/TLab.WebView.Runtime.asmdef`

### Android Plugin

Prebuilt Android browser engine and capture backend.

- [Android AAR](https://github.com/tlabaltoh/tlabwebview/blob/master/Plugins/Android/libTLabWebView-release.aar): native binary · Prebuilt Android plugin containing the actual browser engine and platform rendering. · `Plugins/Android/libTLabWebView-release.aar`
- [Copy Script](https://github.com/tlabaltoh/tlabwebview/blob/master/Plugins/Android/copy.bat): packaging helper · Build/distribution helper for moving the Android plugin into place. · `Plugins/Android/copy.bat`

### Editor

Build-time integration and Android dependency setup.

- [Postprocess Build](https://github.com/tlabaltoh/tlabwebview/blob/master/Editor/Scripts/UnityWebViewPostprocessBuild.cs): build hook · Editor build hook that injects Android packaging and dependency settings. · `Editor/Scripts/UnityWebViewPostprocessBuild.cs`
- [Deps XML](https://github.com/tlabaltoh/tlabwebview/blob/master/Editor/MediationAdapterDependencies.xml): android deps · Editor-time Android dependency configuration for packaging and mediation. · `Editor/MediationAdapterDependencies.xml`
- [Editor asmdef](https://github.com/tlabaltoh/tlabwebview/blob/master/Editor/TLab.WebView.Editor.asmdef): assembly definition · Unity assembly boundary for editor-only tooling. · `Editor/TLab.WebView.Editor.asmdef`

### Samples

Example scenes and runtime usage patterns.

- [Browser Prefab](https://github.com/tlabaltoh/tlabwebview/blob/master/Resources/TLab/WebView/Browser.prefab): prefab entry · Reusable Unity prefab that assembles the browser runtime components. · `Resources/TLab/WebView/Browser.prefab`
- [Sample Scenes](https://github.com/tlabaltoh/tlabwebview/blob/HEAD/Samples/Scenes/Mobile%20Sample.unity): demo scenes · Unity scenes demonstrating setup, lifecycle, and interaction patterns. · `Samples/Scenes/Mobile Sample.unity`

## Connections

- Browser Manager → Browser Container: creates · Manages per-instance browser containers for a scene.
- Browser Container → Browser: hosts · Binds the Unity container to the browser abstraction.
- Browser → IBrowser: implements · Concrete browser implementations satisfy the engine contract.
- Browser → WebView: webview mode · Selects the Android WebView backend when configured.
- Browser → GeckoView: gecko mode · Selects the GeckoView backend when configured.
- Browser Container → Offscreen Capture: captures · Connects browser output to the chosen offscreen capture path.
- Offscreen Capture → Fragment Capture: uses · Fragment capture is the Unity-side frame extraction path.
- Fragment Capture → Native Plugin: drives · Frame transfer and browser actions flow through the native bridge.
- Browser → Native Plugin: calls · Browser operations are delegated to the Android plugin bridge.
- Input Layer → Browser Input: routes to · Generic Unity input is specialized into browser interaction handling.
- Browser Input → Input Field: focuses · Text and keyboard focus are forwarded through the input field bridge.
- Browser Input → Browser Container: targets · Input is dispatched to the active browser instance container.
- Browser Container → Widgets: spawns · Browser events can open Unity overlay widgets.
- Widgets → JS Bridge: reports · Widget interactions feed back into the browser messaging layer.
- Browser → JS Bridge: messages · JS-to-C# communication is handled through the common bridge.
- JS Bridge → Native Plugin: bridges · Browser-side messaging is forwarded through native plugin callbacks.
- Postprocess Build → Deps XML: configures · Build hook applies Android dependency metadata.
- Postprocess Build → Android AAR: packages · Editor build process incorporates the Android binary plugin.
- Editor asmdef → Postprocess Build: contains · Editor assembly hosts build-time tooling.
- Copy Script → Android AAR: distributes · Packaging helper copies the prebuilt native plugin.
- Browser Prefab → Browser Manager: wires · Prefab assembles the main runtime entry point.
- Sample Scenes → Browser Prefab: demonstrates · Sample scenes show how the prefab is placed into a Unity scene.
- Runtime asmdef → Browser Manager: includes · Runtime assembly contains the managed browser stack.
- Android AAR → Native Plugin: backing engine · The bridge delegates to the packaged Android implementation.