qwen-code/packages/webui/docs/WEBUI_PLATFORM_ADAPTER_GUIDE.md

WebUI Platform Adapter Guide (Chrome / Web / Share)

This guide is for extending @qwen-code/webui to new runtime platforms (e.g., Chrome Extension, pure Web pages, Share pages).

For VSCode adapter implementation reference, see: packages/vscode-ide-companion/src/webview/context/VSCodePlatformProvider.tsx

---

1. Core Goals

• Reuse WebUI without modifying UI components.
• Inject platform capabilities via PlatformProvider (messaging, files, login, clipboard, etc.).
• Provide fallback solutions or mark features for missing capabilities.

---

2. PlatformContext Key Points (Minimum Implementation)

Required fields:

• platform: 'chrome' | 'web' | 'share'
• postMessage: Send messages to host
• onMessage: Subscribe to host messages

Optional capabilities (by platform support):

• openFile
• openDiff
• openTempFile
• attachFile
• login
• copyToClipboard
• getResourceUrl
• features (mark capability availability)

Type definitions location: packages/webui/src/context/PlatformContext.tsx

---

3. Adaptation Steps (Recommended Flow)

1. Set up message channel

   • Chrome Extension: chrome.runtime.sendMessage + chrome.runtime.onMessage
   • Web/Share: window.postMessage + message event, or custom event bus

2. Implement PlatformProvider

   • Map platform APIs to PlatformContextValue
   • Return undefined for missing capabilities and set features

3. Application entry integration

   • Wrap with <PlatformProvider value={platformValue}> at platform entry
   • Ensure all UI components are within the Provider

4. Styles and themes

   • Import @qwen-code/webui/styles.css
   • Define CSS variables on platform side (can copy initial values from packages/webui/src/styles/variables.css)

5. Build and dependencies

   • Tailwind uses @qwen-code/webui/tailwind.preset
   • content must include node_modules/@qwen-code/webui/dist/**/*.js

6. Feature validation

   • Message send/receive works (postMessage/onMessage)
   • Clicking file/diff output doesn't throw errors (can fallback)
   • @// completion and input box interactions work

---

4. Reference Implementation (Web Platform Example)

import type React from 'react';
import { PlatformProvider } from '@qwen-code/webui';
import type { PlatformContextValue } from '@qwen-code/webui';

const platformValue: PlatformContextValue = {
  platform: 'web',
  postMessage: (message) => {
    window.postMessage(message, '*');
  },
  onMessage: (handler) => {
    const listener = (event: MessageEvent) => handler(event.data);
    window.addEventListener('message', listener);
    return () => window.removeEventListener('message', listener);
  },
  copyToClipboard: async (text) => navigator.clipboard.writeText(text),
  features: {
    canCopy: true,
  },
};

export const WebPlatformProvider: React.FC<{ children: React.ReactNode }> = ({
  children,
}) => <PlatformProvider value={platformValue}>{children}</PlatformProvider>;

---

5. Chrome Extension Suggested Mapping

• postMessage -> chrome.runtime.sendMessage
• onMessage -> chrome.runtime.onMessage.addListener
• openFile/openDiff -> Trigger background script to open tab / side panel
• attachFile -> chrome.tabs or <input type="file">

---

6. Web/Share Scenario Fallback Strategies

• openFile/openDiff: Display content in new window/modal
• openTempFile: Generate Blob and open or download
• login: Redirect to login URL or popup login window

---

7. Common Pitfalls

• Tailwind styles not working: content missing @qwen-code/webui
• Theme colors not working: styles.css not loaded or CSS variables not set
• postMessage no response: Host side hasn't registered corresponding message channel